Api Reference Documentation

What it does

This skill generates clear, structured documentation for API endpoints based on raw specifications or code. It transforms technical details into readable guides that explain request parameters, response formats, and usage examples.

When to use it

• You have a Swagger/OpenAPI JSON file but need human-readable text descriptions for your team.
• You are documenting a new internal microservice and want consistent formatting across all endpoints.
• You need to convert complex GraphQL schemas into simple "how-to" instructions for frontend developers.

Key capabilities

• Parses raw API definitions (JSON, YAML, or Markdown) to extract endpoint logic.
• Generates standardized sections including headers, query parameters, and response bodies.
• Produces usage examples with realistic request/response pairs in code blocks.
• Adapts tone and depth based on the target audience (e.g., developers vs. product managers).

Example prompts

• "Convert this OpenAPI JSON specification into a Markdown documentation file with clear headers for each endpoint."
• "Explain how to use the /users API endpoint, including required authentication headers and common error codes."
• "Generate a quick-start guide for integrating the payment gateway API, focusing on the POST /charge method."

Tips & gotchas

Ensure you provide complete context, such as the full OpenAPI spec or relevant code snippets, to avoid hallucinated parameters. If your API uses custom authentication flows, explicitly describe those steps so the agent can include them in the generated guide.