We have received a lot of feedback about GitBook's API methods blocks. It's one of the most controversial feature of the new GitBook. A lot of you love it, and at the same time, it has a lot of flaws.

This post serves as an announcement that we are looking to improve API blocks in the long-term, and it could result in a complete redesign of the feature. It also serves to gather and summarize all your feedback, and discuss possible

solutions with you.


Long term and capability issues


# Integration with standard formats (Swagger, OpenAPI)

This could be a great long-term improvement for API blocks.

# Description should support rich blocks

Like hints, quotes, code blocks, links, bold etc.

It could be especially useful for deprecation warnings

# Parameters descriptions should support richer formatting

Such as links, bold, inline code.

Or even lists and code blocks.

# Float types for request parameters

# We should be able to add examples of request parameters

For example for request body.

# Missing standard way to document response headers


Usability issues


# Description lines height is too small

# Reordering parameters

# New parameters are added to top of their categories

# It's not obvious how to add specific response code

Some people only discover the "+ Add Response Example" button, but they don't see that they can edit the code name directly.

# Copying API methods or part of them is hard

# Pasting inside API methods does not work sometimes