Skip to content
Merged
Show file tree
Hide file tree
Changes from 14 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
33 changes: 33 additions & 0 deletions extend/contribute/api-docs/checklist.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,33 @@
---
navigation_title: Checklist
---

# API docs checklist

Use this checklist to verify the quality, completeness, and consistency of your API docs contributions.

## Structure, organization, and metadata
- Include required [OpenAPI document info](./organize-annotate.md#add-open-api-document-info)
- Include [OpenAPI specification version](./organize-annotate.md#add-openapi-specification-version)
- Define unique [operation identifiers](./organize-annotate.md#add-operation-identifiers) using camelCase
- Use consistent [tags](./organize-annotate.md#group-apis-with-tags) to group related operations
- Document [API lifecycle status](./organize-annotate.md#specify-api-lifecycle-status) (availability, stability, version information)
- Mark deprecated APIs and properties with appropriate notices
- Document [required permissions](./organize-annotate.md#document-required-permissions) for each operation

## Content quality and completeness

- Write clear [summaries](./guidelines.md#write-summaries) (30 characters max, start with a verb)
- Write detailed [descriptions](./guidelines.md#write-descriptions) for operations, parameters, properties, tags etc.
- Document all [path parameters](./guidelines.md#document-path-parameters) with constraints and formats
- Provide descriptions for non-obvious [enum values](./guidelines.md#document-enum-values)
- Specify [default values](./guidelines.md#set-default-values) for optional parameters
- Include realistic [examples](./guidelines.md#add-examples) with helpful descriptions
- Add [links](./guidelines.md#add-links) to related operations and documentation

## Quality assurance

- Preview your changes locally before submitting (see [Contribute locally: Elasticsearch quickstart](./quickstart.md))
- [Lint your API docs](guidelines.md#lint-your-api-docs) to identify and fix issues
- Check all links to ensure they work correctly
- Ensure examples are realistic and error-free
Loading
Loading