Documentation/API documentation

API documentation is a form of technical reference, that describes the machinery that a user needs to work with. This page compiles resources and tools for documenting APIs.

Quickstart

API Documentation Template

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 If-Modified-Since: Wed, 21 Oct 2015 07:28:00 GMT Returns the response only if the content has changed since the provided timestamp. Takes a timestamp in the format <day-name>, <day> <month> <year> <hour>:<minute>:<second> GMT.

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:

# Search English Wikipedia for 10 articles about Earth
$ curl https://api.wikimedia.org/core/v1/wikipedia/en/search/page?q=earth&limit=10

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 {"example": "example"}

Response schema

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

Tools

OpenAPI (specification)

OpenAPI (formerly known as Swagger) is a format for creating machine-readable API descriptions.

Examples

OpenAPI spec for the Link Recommendation API

Evaluation

Benefits:

OpenAPI works with a growing set of open-source tools, including spec generators, validators, sandboxes, and HTML generators.

Issues:

Because OpenAPI is designed to be machine readable, OpenAPI specs are not easy for people to write or read. Choosing to use OpenAPI for your project means setting up tools to generate and display the spec.
The purpose of the license field is ambiguous.^[1] (Does it refer to the license of the API's source code or to the data returned by the API?) Instead of using the license field, provide information about relevant license in the description.

swag (OpenAPI, Go)

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

Examples

Device Analytics
- Annotations in main.go (supplemented by api.md)
- Annotations in handler
- Annotations in entity
- Swag output and spec files in /docs
Process for setting up docs with swag

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
Allows the API description to be stored in a separate markdown file, which avoids having long descriptive text inside the code file

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.^[2]
Swag fails if you use tabs in annotations in main.go but oddly not in other files.
Swag reorders response properties alphabetically. You can override this behavior by adding extensions:"x-order=1" to each property in the struct, but this syntax can be difficult to maintain, especially for large responses.
Although Swag supports parsing dependencies for annotations, Swag requires response objects to be defined as structs. If a response is not defined as a struct, you can define the response in an endpoint annotation.^[3] For example: // @failure 400 {object} object{detail=string,method=string} "Bad request message"

Resources

RapiDoc (OpenAPI, UI)

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

Examples

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.
Very small text on mobile

swagger-ui (OpenAPI, UI)

Swagger UI is a user interface for reading OpenAPI specifications. Swagger UI includes a built-in API sandbox and is the most popular tool for viewing OpenAPI specifications.

Evaluation

Benefits:

Due to the widespread use of Swagger UI, many users are familiar with the interface.

Issues:

Compared to more lightweight tools like RapiDoc, Swagger UI has more dependencies and is more complicated to run. A review by the Wikimedia Foundation security team found Swagger UI to pose a medium level of risk.^[4]
The layout of Swagger UI is based on expandable and collapsable sections. As a result, it can be easy to get lost on the page since there is no indication of which section the user is currently viewing. In addition, collapsed sections do not support navigating the page using control+f.
Users must first select the Try it out button before they can interact with the sandbox.
The sandbox automatically encodes path parameters. See the note in the RapiDoc section.
The section that documents the response schema is difficult to see and collapsed by default, requiring users to select several small arrows before viewing the content.
Very small text on mobile

apiDoc (UI)

The apiDoc tool creates HTML documentation from code annotation. See the docs for an example of the HTML output.

Evaluation

Benefits:

apiDoc supports JS, PHP, and several other languages.

Issues:

The annotation format is more compact than swagger-php (15 lines added to a handler), resulting in less clutter in the source files. However, example responses are not generated from response schemas, so examples need to be embedded in the source file. Since many MediaWiki-related API responses are long and complex, this would result in too much clutter in source files.
There's a nice sample request feature, but it only accepts a sample URL, not the ability to customize path or query parameters. This makes the parameter interface for sample requests a bit confusing.
No obvious support for translation, but it may be possible through the extension interface.

swagger-php (OpenAPI, PHP)

The zircote/swagger-php tool generates an OpenAPI spec from code annotations.

Evaluation

Benefits:

Supports PHP

Issues:

swagger-php requires adding a significant number of lines to code files. In testing the tool, I had to add 100 lines added to the handler and 12 lines added to the entry point, compared with 84 lines in the resulting spec.
swagger-php supports context-aware annotations, but it seems that our handlers don't work the same way as the examples.
swagger-php requires response definitions to be in the same annotation block as the path definition. Schema properties can be distributed, but it requires extra annotation syntax, adding complexity and further code file bloat.

Widdershins (OpenAPI, Markdown)

Widdershins converts an OpenAPI specification to Markdown.

[1] ttps://github.com/OAI/OpenAPI-Specification/issues/726

[2] ttps://github.com/swaggo/swag/issues/548

[3] ttps://github.com/swaggo/swag/issues/938

[4] :T325558

[1]

[2]

[3]

[4]