Skip to content

Home

Development

IDEs

API Explorer

Quick start tutorial: Documenting a RESTful API

Estimated time to complete: 2-4 minutes

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.

Adding path summary

Adding path summary

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).

Adding operation summary

Adding operation summary

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.

Adding parameter description

Adding parameter description

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.

Gloop REST API editor, Preview tab

Gloop REST API editor, Preview tab

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:

Previewing a documented API in API Explorer


  1. Values can also be edited by by pressing while the row is highlighted.