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
# 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