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