api-documenter

# 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 ```javascript // 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 ```python # 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 ```yaml 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 ```javascript // 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: ```json { "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 1. I generate OpenAPI spec 2. You need user guide → Invoke **@docs-writer** sub-agent 3. Sub-agent creates complete documentation site ## Integration ### With Swagger UI ```javascript // 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: ```bash # 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: ```bash 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 1. **Keep comments updated** - Documentation follows code 2. **Use type hints** - TypeScript, Python types help 3. **Include examples** - Real-world request/response 4. **Document errors** - All possible error responses 5. **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