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
editTypes of API documentation
edit- 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
editThe API reference is a complete description of the behavior of the API.
Documenting a REST endpoint
editA complete reference for a REST API endpoint should include these elements.
Endpoint name
editA short phrase describing the endpoint’s essential function, used for navigation. For example: Get page history
Endpoint description
editThe 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
editThe endpoint path, including required URL parameters. For example: /core/v1/{project}/{language}/page/{title}.
Method
editGET, POST, etc. Conventionally, an endpoint that supports multiple methods is represented in the docs as separate endpoints.
Request parameters
editFor 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
editFor 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
editIf 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)
editRequest 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
editInformation 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
editIncludes the property name, type, required/optional, and a description. Example: latest, required, string, API route to get the 20 latest revisions.
Tools
editOpenAPI (specification)
editOpenAPI (formerly known as Swagger) is a format for creating machine-readable API descriptions.
Examples
editEvaluation
editBenefits:
- 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 thelicense
field, provide information about relevant license in thedescription
.
swag (OpenAPI, Go)
editSwag is a tool for Go that generates an OpenAPI specification based on a mix of code annotations and the code itself.
Examples
edit- Device Analytics
- Process for setting up docs with swag
Evaluation
editBenefits:
- 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
edit- Available annotations
- Available param types
- Available data types for params
- Example from the swag docs
RapiDoc (OpenAPI, UI)
editRapiDoc converts an OpenAPI specification into an HTML page with a built-in sandbox.
Examples
editEvaluation
editBenefits:
- 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)
editSwagger 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
editBenefits:
- 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)
editThe apiDoc tool creates HTML documentation from code annotation. See the docs for an example of the HTML output.
Evaluation
editBenefits:
- 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)
editThe zircote/swagger-php tool generates an OpenAPI spec from code annotations.
Evaluation
editBenefits:
- 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)
editWiddershins converts an OpenAPI specification to Markdown.