|
| 1 | +--- |
| 2 | +navigation_title: Checklist |
| 3 | +--- |
| 4 | + |
| 5 | +# API docs checklist |
| 6 | + |
| 7 | +Use this checklist to verify the quality, completeness, and consistency of your API docs contributions. |
| 8 | + |
| 9 | +## Structure, organization, and metadata |
| 10 | +- Include required [OpenAPI document info](./organize-annotate.md#add-open-api-document-info) |
| 11 | +- Include [OpenAPI specification version](./organize-annotate.md#add-openapi-specification-version) |
| 12 | +- Define unique [operation identifiers](./organize-annotate.md#add-operation-identifiers) using camelCase |
| 13 | +- Use consistent [tags](./organize-annotate.md#group-apis-with-tags) to group related operations |
| 14 | +- Document [API lifecycle status](./organize-annotate.md#specify-api-lifecycle-status) (availability, stability, version information) |
| 15 | +- Mark deprecated APIs and properties with appropriate notices |
| 16 | +- Document [required permissions](./organize-annotate.md#document-required-permissions) for each operation |
| 17 | + |
| 18 | +## Content quality and completeness |
| 19 | + |
| 20 | +- Write clear [summaries](./guidelines.md#write-summaries) (between 5-45 characters) |
| 21 | +- Write detailed [descriptions](./guidelines.md#write-descriptions) for operations, parameters, properties, tags etc. |
| 22 | +- Document all [parameters](./guidelines.md#document-parameters) and explain how changing defaults affects behavior |
| 23 | +- Provide descriptions for non-obvious [enum values](./guidelines.md#document-enum-values) |
| 24 | +- Specify [default values](./guidelines.md#set-default-values) for optional parameters |
| 25 | +- Include realistic [examples](./guidelines.md#add-examples) with helpful descriptions |
| 26 | +- Add [links](./guidelines.md#add-links) to related operations and documentation |
| 27 | + |
| 28 | +## Quality assurance |
| 29 | + |
| 30 | +- Preview your changes locally before submitting (see [Contribute locally: Elasticsearch quickstart](./quickstart.md)) |
| 31 | +- [Lint your API docs](guidelines.md#lint-your-api-docs) to identify and fix issues |
| 32 | +- Check all links to ensure they work correctly |
| 33 | +- Ensure examples are realistic and error-free |
0 commit comments