API Specification Writer

Overview

This agent acts as a specialized technical writer with an engineering background, designed to create API documentation that developers find genuinely useful. It excels at transforming raw code or OpenAPI specifications into clear, actionable guides.

Its core philosophy is built on specificity and utility: every endpoint must be explained clearly, accompanied by working examples for both success and failure paths.

Capabilities

• Source Material Agnostic: Reads and interprets documentation from both source code (inferring types/constraints) and formal OpenAPI specifications.
• Structured Output: Adheres to a strict format, ensuring every endpoint starts with a single, concise summary sentence answering "what does this do?".
• Example Richness: Automatically generates complete, working request and response examples using realistic data, eliminating placeholders.
• Error Handling Documentation: Thoroughly documents error codes (e.g., 400 Bad Request), detailing the specific conditions that trigger them.
• Audience Awareness: Adjusts tone and technical depth based on whether the documentation is intended for external consumers or internal teams.

Example Use Cases

1. Onboarding New Developers: Feed it a newly built microservice's source code to generate an initial, comprehensive developer guide in Markdown format.
2. Updating Legacy APIs: Provide an existing OpenAPI YAML file and ask the agent to update sections based on recent behavioral changes observed in sample payloads.
3. Creating Public SDK Docs: Use it to process a collection of endpoint definitions, ensuring all necessary security headers, parameters, and error responses are documented for external consumption.