Documentation/API documentation

This page compiles resources and tools for documenting APIs.

Types of API documentation

 * Introduction
 * The introduction provides basic information about the API such as the API framework, data formats, and an overview of the functionality offered by the API.


 * Explanation
 * Explanations help users understand how to use the API. For example, a guide to authenticating API requests or a description of the error message format.


 * Tutorial
 * A tutorial is a step-by-step guide to using the API to accomplish a task.


 * Reference
 * The API reference is a complete description of the behavior of the API.

API reference
The API reference is a complete description of the behavior of the API.

Documenting a REST endpoint
A complete reference for a REST API endpoint should include these elements.

Endpoint name
A short phrase describing the endpoint’s essential function, used for navigation. For example: Get page history

Endpoint description
The text presented under the main endpoint heading, describing the use case for the endpoint and any helpful information. For example: Returns information about the latest revisions to a wiki page, in segments of 20 revisions, starting with the latest revision.

Path
The endpoint path, including required URL parameters. For example: /core/v1/{project}/{language}/page/{title}.

Method
GET, POST, etc. Conventionally, an endpoint that supports multiple methods is represented in the docs as separate endpoints.

Request parameters
For each parameter:


 * name of the parameter
 * parameter type: path or query
 * required/optional
 * an example
 * a description

For example: id, path, required, 38930, Page identifier

Request headers
For each request header the API supports:


 * name of the header
 * an example
 * a description

For example: If-Modified-Since Returns the response only if the content has changed since the provided timestamp. Takes a timestamp in the format.

Request schema
If the endpoint takes a request body, for each property:


 * name
 * type (integer, string, etc.)
 * required/optional
 * an example
 * a description

For example: id, integer, required, Revision identifier for the latest revision.

Request examples (sample code)
Request examples in a few popular programming languages. These example should encourage best practices and make use of important parameters where possible. For example:

Responses
Information about possible responses returned by the endpoint. Includes the status code, a description, and an example or embedded sandbox. For example: 200 Success

Response schema
Includes the property name, type, required/optional, and a description. Example: latest, required, string, API route to get the 20 latest revisions.

swag (Go)
Swag is a tool for Go that generates an OpenAPI specification based on a mix of code annotations and the code itself.

Evaluation
Benefits:


 * Swag gets information about the response object from the struct without needing additional annotations. This helps limit the number of annotations needed per endpoint and reduces duplication of information.
 * Robust feature set
 * Outputs both JSON and YAML

Issues:


 * Each parameter must be defined on one line. Depending on the length of the description, this can result in very long annotation lines, which can be difficult to read. Since most of the parameters are shared between services, maybe we could find a way to reduce duplication of these docs.
 * Swag only supports OpenAPI 2.0, not the latest version: 3.0.
 * Swag fails if you use tabs in annotations in main.go but oddly not in other files.

RapiDoc (UI)
RapiDoc converts an OpenAPI specification into an HTML page with a built-in sandbox.

Examples

 * API spec reader on Toolforge
 * Toolhub API (source)

Evaluation
Benefits:


 * Built-in API sandbox
 * Sidebar navigation is easier to use than the expandable sections used by Swagger UI
 * Helpful feature that fills in parameters with example values, making it easier to try out the sandbox, not offered by Swagger UI
 * Dark mode, not offered by Swagger UI
 * Support for color and logo customization

Issues:


 * Only supports specs in JSON format, not YAML
 * Poor color contrast on small text in dark mode
 * No option to toggle between light mode and dark mode
 * The sandbox automatically encodes path parameters, which is confusing for parameters like page titles that need to be encoded. If you put an encoded page title into the sandbox, it will encode it again, resulting in an invalid page title. This is an issue with both RapiDoc and Swagger UI and seems to be the expected behavior of both tools. As a workaround, we can call out this difference in the docs, but it may still cause confusion.