Quick start tutorial: Documenting a RESTful API
When publishing a public API, it is custom to publish the API with documentation. Documentation is extremely useful for external developers; it teaches them what an API does, and lets them know which request configurations are acceptable, and what kind of responses to expect.
Martini makes it easy to write documentation for APIs. You simply use the Gloop REST API editor, and write documentation in the same place where you configure operations. As an added bonus, you can use Markdown in the documentation for text formatting as well.
Any documentation you add to a Gloop API will automatically be ported to the API's equivalent Swagger, OpenAPI, and Postman definitions. Documentation will also be visible when an operation is viewed in the API Explorer.
This page will go over the process of adding documentation to a Gloop REST API, and previewing the resulting documentation in the Gloop REST API editor, and API Explorer.
Prerequisites to making an API discoverable
This guide assumes you already have an existing API. If you're not yet acquainted with this topic, it's recommended to learn more by reading the tutorial page on creating an API first.
Add general and documentation information
Values you provide for fields under the General and Documentation tab will be used in the resulting Swagger, OpenAPI, and Postman definitions. Hence, it is important you populate these fields in order to produce a fully-documented API.
Add path information
To document a path, expand its node and then provide values for its Description and Summary nodes by double clicking the Value column1.
What's the difference between Description and Summary?
The Description node should contain the description of a path, while the Summary node should contain a summary of the description itself.
Add operation information
To document an operation, expand its node and then provide values for Description and Summary by double clicking on their respective Value columns1. If the Description is left empty, Martini will automatically use the selected service's comment for its value (if it has a comment).
Add parameter and response information
To document a parameter, expand its node and then provide a value for Description by double clicking its Value column1. If the Description is left empty, Martini will automatically use the selected input property's comment for its value (if it has one), as shown in the screenshot below.
This procedure is also applicable to responses; except when it's empty, it will use the selected output property's comment.
Previewing generated schemas
If you would like to see how the Swagger, OpenAPI, and Postman definitions look, save the API, then select the Preview tab. Use the dropdown on the top right-hand side to switch between available formats.
Previewing in API Explorer
The API Explorer reuses the automatically generated Swagger schemas to render an interactive user interface for existing APIs. Thus, if you were to open the API in API Explorer, the documentation will also be visible in the user interface: