About api documentation generator
Turn an OpenAPI or Swagger file into readable Markdown documentation that can go straight into a README or wiki.
Good API documentation has
- A clear description for every endpoint.
- Request and response examples.
- Error codes with explanations.
- Notes on authentication and rate limits.
A worked example
For a specification with a users tag, the generated document has an Overview, an Authentication section and one heading for each endpoint, such as 'GET /users/{id}', with a table of parameters, an example request and the possible responses. Paste it into a README or wiki.
Improve the output
- Add summaries and descriptions in the specification, since they appear in the document.
- Include example values for every field.
- Explain error formats and rate limits once, in the overview.
Publishing
Commit the Markdown beside your code, or publish it with a documentation site generator, so that every release has matching documents.
