API docs checklist
Use this checklist to verify the quality, completeness, and consistency of your API docs contributions.
- Include required OpenAPI document info
- Include OpenAPI specification version
- Define unique operation identifiers using camelCase
- Use consistent tags to group related operations
- Document API lifecycle status (availability, stability, version information)
- Mark deprecated APIs and properties with appropriate notices
- Document required permissions for each operation
- Write clear summaries (between 5-45 characters)
- Write detailed descriptions for operations, parameters, properties, tags etc.
- Document all parameters and explain how changing defaults affects behavior
- Provide descriptions for non-obvious enum values
- Specify default values for optional parameters
- Include realistic examples with helpful descriptions
- Add links to related operations and documentation
- Preview your changes locally before submitting (see Quickstarts)
- Lint your API docs to identify and fix issues
- Check all links to ensure they work correctly
- Ensure examples are realistic and error-free