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
Guys when I create an internla link inside an api method type: object it's not working. When it's publish the text dosen't have the link
When :(
Reordering of parameters is sorely needed, but just having new ones appended to the bottom of a block instead of the top would be 90% there - surely this is a relatively quick thing to change?
It would extremely helpful to have the ability to add headers to the response section of an API. This would prove useful in communicating back to consumers the various headers that they would be concerned with. Rounds out the API documentation quite well.
When pasting a value into paramenter decription field by the shortcut (both ctrl-v and ctrl-shift-v), parameter disapears :(
In the "API Method" block, clicking "Add a parameter" should append the new parameter to the bottom of the list, not insert it at the top.
In the "API Method" block, I would like the ability to reorder parameters within groups of the same type, preferably via drag-n-drop.
For API Methods, allow for parameter cast types to have defaults and acceptable inputs listed in a structured consistent way beyond the paragraph explanation.
As an example, if I have a query parameter of format with a type of string, then there should be a standard way of listing the default applied or acceptable designations.
I'd like to have a callout for DEPRECATED, same size and look as the API method with the border and lettering red (e.g., GET, PUT, etc.). Ideally it should be next to the API method, so for example: GET DEPRECATED Retrieve all user accounts.
I love how easy it is to document our REST API using the API Method component. I would love you to enhance this component to do the following:
- Fix the description field so that multiple lines don't get scrunched up together.
- Allow callouts in the description body.
- Allow examples of the request body to be inserted into the Request tab.
Thanks!
Here is a list of related post (I'm not merging them for now)
https://gitbook.canny.io/feature-requests/p/api-method-default-accepted
https://gitbook.canny.io/feature-requests/p/api-method-reorder-parameters
https://gitbook.canny.io/feature-requests/p/api-method-add-a-parameter-to-bottom-of-list
https://gitbook.canny.io/feature-requests/p/ctrl-v-in-api-block
https://gitbook.canny.io/feature-requests/p/deprecated-callout
https://gitbook.canny.io/feature-requests/p/enhance-api-methods
https://gitbook.canny.io/feature-requests/p/add-header-support-for-api-responses
https://gitbook.canny.io/feature-requests/p/import-and-sync-with-swagger-files
I am not sure if I understand what you meant. You'd like to add an URL as a parameter's type because the type is documented somewhere else?
@Gabin: Hi Gabin. Create a new block type: API Method, then new parameter type: object. Inside the object declaration, select some word to add a link. You write the URL but this word, dosen't have the link action, neither the color of a link.
Thanks for your time :)
@VOUSYS: Thanks, understood! 👌
This would be a massive improvement for us, namely rich formatting everywhere and sample request bodies. The other points also seem good, especially reordering params, but are less critical to conveying the information we need to.