Api Documentation Writer

What it does

This skill assists in creating comprehensive and developer-friendly API documentation. It focuses on generating clear explanations, complete details of parameters and responses (including edge cases), and ensuring documentation remains synchronized with the API's behavior. The skill supports OpenAPI/Swagger specifications and provides guidance for authentication, code examples in multiple languages, and overall developer experience best practices.

When to use it

• When creating initial API documentation from scratch.
• To update existing API documentation to reflect changes in endpoints or functionality.
• To ensure consistent formatting and adherence to documentation standards (Clear, Complete, Current).
• For generating code examples for developers using the API.
• When needing to document error codes and provide remediation steps.

Key capabilities

• Generates OpenAPI/Swagger specifications.
• Documents endpoint requests and responses with examples.
• Provides guidance on authentication methods.
• Includes code examples in popular programming languages (specific languages not listed).
• Supports documenting error codes and remediation steps.
• Adheres to the "Three C's" of documentation: Clear, Complete, Current.

Example prompts

• “Generate OpenAPI documentation for my /users endpoint.”
• “Document the authentication process for accessing the API.”
• “Create a code example in Python showing how to list users with pagination.”

Tips & gotchas

• The skill is designed to document public endpoints, not internal or private ones.
• Ensure you provide sufficient context about your domain; avoid assuming readers have prior knowledge.
• Regularly review and update the documentation to prevent it from drifting away from the actual API implementation.