"As an API developer, I want changes I make to API definitions in my code to be updated automatically in the documentation, so that it's always up-to-date with the latest interfaces in production."
### Generation
The best documentation is generated from the code itself (either source or tests) or from as close to the code as possible.
### Requirements
* Versioning by major version
* Support for localization
### Minimum API docs
Information included per endpoint:
- Group
- Name
- Description
- Path
- Method
- Example request URL
- Request parameters table
- Parameter name
- Required/optional
- Example
- Description
- Headers (if available, including the name, example, and description)
- Request body example (if required)
- Request body schema (if required, including the name, type, required/optional, and a description)
- Responses
- Response code
- Response body example (if applicable)
- Response body schema (if applicable, including the name, type, required/optional, and a description)
### Better API docs
Multilingual sample code:
- In addition to the information listed above, each endpoint includes sample code for making requests in multiple programming languages.
Automation:
- Docs are automatically generated, ensuring that they are always 100% accurate.
Sandbox:
- Docs include a sandbox with which users can test requests and see live responses.
### Output format
We’d like users to access the docs within MediaWiki. However, the reference docs should not be editable within MediaWiki since they’re being generated automatically.
References:
- Docs for the Action API can be pulled into a wiki page per module with [[ https://www.mediawiki.org/wiki/API:Help | API:Help ]] (for example: `{{Api help|parse}}`). This means that the page structure is maintained manually and the surrounding content is indexed by the wiki search.
- In contrast, most API docs are served as a single long page with specialized navigation ([[ https://stripe.com/docs/api | example ]]).