Documentation/API documentation/Tools

This page outlines the functionality, benefits, and drawbacks of some popular documentation tools for API documentation.

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. (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.
• 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. For example: // @failure 400 {object} object{detail=string,method=string} "Bad request message"

Resources

• Available annotations
• Available param types
• Available data types for params
• Example from the swag docs

RapiDoc (OpenAPI, 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.
• 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.
• 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.