API Documenter Skill

Auto-generate API documentation from code.

When I Activate

• ✅ API endpoints added/modified

• ✅ User mentions API docs, OpenAPI, or Swagger

• ✅ Route files changed

• ✅ Controller files modified

• ✅ Documentation needed

What I Generate

OpenAPI 3.0 Specifications

• Endpoint descriptions

• Request/response schemas

• Authentication requirements

• Example payloads

• Error responses

Formats Supported

• OpenAPI 3.0 (JSON/YAML)

• Swagger 2.0

• API Blueprint

• RAML

Examples

Express.js Endpoint

// You write: /**

• Get user by ID
• @param {string} id - User ID
• @returns {User} User object */ app.get('/api/users/:id', async (req, res) => { const user = await User.findById(req.params.id); res.json(user); });

// I auto-generate OpenAPI spec: paths: /api/users/{id}: get: summary: Get user by ID parameters: - name: id in: path required: true description: User ID schema: type: string responses: '200': description: User found content: application/json: schema: $ref: '#/components/schemas/User' example: id: "123" name: "John Doe" email: "john@example.com" '404': description: User not found

FastAPI Endpoint

You write:

@app.get("/users/{user_id}") def get_user(user_id: int) -> User: """Get user by ID""" return db.query(User).filter(User.id == user_id).first()

// I auto-generate: paths: /users/{user_id}: get: summary: Get user by ID parameters: - name: user_id in: path required: true schema: type: integer responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/User'

Complete OpenAPI Document

openapi: 3.0.0 info: title: User API version: 1.0.0 description: API for user management

servers:

• url: https://api.example.com/v1

paths: /api/users: get: summary: List all users responses: '200': description: Users array content: application/json: schema: type: array items: $ref: '#/components/schemas/User'

components: schemas: User: type: object properties: id: type: string name: type: string email: type: string format: email

Detection Logic

Framework Detection

I recognize these frameworks automatically:

• Express.js (Node.js)

• FastAPI (Python)

• Django REST (Python)

• Spring Boot (Java)

• Gin (Go)

• Rails (Ruby)

Comment Parsing

I extract documentation from:

• JSDoc comments (/** */ )

• Python docstrings

• JavaDoc

• Inline comments with decorators

Documentation Enhancement

Missing Information

// Your code: app.post('/api/users', (req, res) => { User.create(req.body); });

// I suggest additions: /**

• Create new user
• @param {Object} req.body - User data
• @param {string} req.body.name - User name (required)
• @param {string} req.body.email - User email (required)
• @returns {User} Created user
• @throws {400} Invalid input
• @throws {409} Email already exists */

Example Generation

I generate realistic examples:

{ "id": "usr_1234567890", "name": "John Doe", "email": "john.doe@example.com", "createdAt": "2025-10-24T10:30:00Z", "verified": true }

Relationship with @docs-writer

Me (Skill): Auto-generate API specs from code @docs-writer (Sub-Agent): Comprehensive user guides and tutorials

Workflow

• I generate OpenAPI spec

• You need user guide → Invoke @docs-writer sub-agent

• Sub-agent creates complete documentation site

Integration

With Swagger UI

// app.js const swaggerUi = require('swagger-ui-express'); const spec = require('./openapi.json'); // Generated by skill

app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(spec));

With Postman

Export generated OpenAPI spec:

Import into Postman for API testing

File → Import → openapi.json

With Documentation Sites

• Docusaurus: API docs plugin

• MkDocs: OpenAPI plugin

• Redoc: OpenAPI renderer

• Stoplight: API design platform

Customization

Add company-specific documentation standards:

cp -r ~/.claude/skills/documentation/api-documenter
~/.claude/skills/documentation/company-api-documenter

Edit to add:

- Company API standards

- Custom response formats

- Internal schemas

Sandboxing Compatibility

Works without sandboxing: ✅ Yes Works with sandboxing: ✅ Yes

• Filesystem: Writes OpenAPI files

• Network: None required

• Configuration: None required

Best Practices

• Keep comments updated - Documentation follows code

• Use type hints - TypeScript, Python types help

• Include examples - Real-world request/response

• Document errors - All possible error responses

• Version your API - Include version in endpoints

Related Tools

• @docs-writer sub-agent: User guides and tutorials

• readme-updater skill: Keep README current

• /docs-gen command: Full documentation generation