api-documentation

name	api-documentation
author	JM Labs (Javier Montaño)
version	1.0.0
description	API documentation: OpenAPI/Swagger spec generation, endpoint docs, request/response examples, authentication docs. Complements api-design. [EXPLICIT] Trigger: "API docs", "OpenAPI", "Swagger", "endpoint documentation", "API reference"
allowed-tools	["Read","Write","Glob","Grep","Bash"]

Api Documentation

"Method over hacks. Evidence over assumption."

TL;DR

Generates API documentation from code or specs: OpenAPI 3.0 specification files, Swagger UI setup, endpoint reference with request/response examples, authentication documentation, and error code catalog. Complements api-design with developer-facing docs. [EXPLICIT]

Procedure

Step 1: Discover

• Read existing code and identify current patterns
• Check for existing documentation or configuration
• Identify gaps and improvement opportunities

Step 2: Analyze

• Evaluate options and select the best approach for the project context
• Consider Constitution principles (XIII Think First, XIV Simple First)
• Map to quality gates

Step 3: Execute

• Implement the solution following established patterns
• Apply evidence tags to all claims
• Generate output using brand template if HTML

Step 4: Validate

• Verify implementation works correctly
• Check against quality criteria
• Evidence tags applied to all claims

Quality Criteria

• Implementation follows established patterns
• Evidence tags applied to all claims
• Tested and verified
• Constitution-compliant

Related Skills

• api-design — API contract design
• rest-api-development — REST implementation
• cloud-functions — Firebase Functions API docs

Usage

Example invocations:

• "/api-documentation" — Run the full api documentation workflow
• "api documentation on this project" — Apply to current context

Assumptions & Limits

• Assumes access to project artifacts (code, docs, configs) [EXPLICIT]
• Requires English-language output unless otherwise specified [EXPLICIT]
• Does not replace domain expert judgment for final decisions [EXPLICIT]

Edge Cases

Scenario	Handling
Empty or minimal input	Request clarification before proceeding
Conflicting requirements	Flag conflicts explicitly, propose resolution
Out-of-scope request	Redirect to appropriate skill or escalate