api-documenter · alirezarezvani — Claude Code skill: API docs
The api-documenter skill builds API specifications from routes and code comments. Use it when endpoints change or the project needs an OpenAPI document.
MIT ★ 788 updated 2026-07-03
npx skills add alirezarezvani/claude-code-tresor --skill api-documenter -a claude-codeWhat api-documenter does
The skill reads route definitions and comments, then produces API documentation. It can generate OpenAPI 3.0 and Swagger 2.0 specs, as well as API Blueprint and RAML files. Generated docs can describe request and response schemas, authentication, examples, and error cases.
It recognises Express.js, FastAPI, Django REST, Spring Boot, Gin, and Rails. For source details, it reads JSDoc, Python docstrings, JavaDoc, and inline comments with decorators; its available tools are Read, Write, and Grep. You can feed an OpenAPI spec to Swagger UI or import it into Postman. The skill writes files locally and does not need network access.
It works with sandboxing enabled or disabled. Documentation follows the comments, so stale comments produce stale specs. The README points to the separate @docs-writer sub-agent for user guides and tutorials.
What it helps with
- generate an OpenAPI spec from project routes
- document API parameters and responses from code comments
- add request examples and error cases to API docs
- prepare a spec for import into Postman
Example prompts for the agent
- Generate an OpenAPI spec for the project's new routes.
- Update the API documentation after changes to the controllers.
- Create a spec I can import into Postman.
How to install api-documenter
1Skills CLI (Vercel)
npx skills add alirezarezvani/claude-code-tresor --skill api-documenter -a claude-code2Manually: put the files in place
~/.claude/skills/api-documenter/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/api-documenter/
1Skills CLI (Vercel)
npx skills add alirezarezvani/claude-code-tresor --skill api-documenter -a codex2Manually: put the files in place
.agents/skills/api-documenter/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add alirezarezvani/claude-code-tresor --skill api-documenter -a cursor2Manually: put the files in place
.cursor/skills/api-documenter/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install alirezarezvani/claude-code-tresor skills/documentation/api-documenter2Manually: put the files in place
.github/skills/api-documenter/SKILL.md1Skills CLI (Vercel)
npx skills add alirezarezvani/claude-code-tresor --skill api-documenter -a gemini-cli2Platform CLI
gemini skills install https://github.com/alirezarezvani/claude-code-tresor --path skills/documentation/api-documenterManually: put the files in place
.devin/skills/api-documenter/SKILL.mdThe legacy .windsurf/skills/ path still works
Claude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about api-documenter
How do I install api-documenter in Claude Code?
Run npx skills add alirezarezvani/claude-code-tresor --skill api-documenter -a claude-code, then use ~/.claude/skills/api-documenter/SKILL.md.
What does api-documenter do?
It creates API specifications from routes and code comments. Supported output formats include OpenAPI 3.0, Swagger 2.0, API Blueprint, and RAML.
Which frameworks does api-documenter recognise?
It recognises Express.js, FastAPI, Django REST, Spring Boot, Gin, and Rails. It can extract descriptions from sources such as JSDoc, Python docstrings, and JavaDoc.
Source text
SKILL.md · MIT
---
name: api-documenter
description: Auto-generate API documentation from code and comments. Use when API endpoints change, or user mentions API docs. Creates OpenAPI/Swagger specs from code. Triggers on API file changes, documentation requests, endpoint additions.
allowed-tools: Read, Write, Grep
---
# 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: "[email protected]"
'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": "[email protected]",
"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
© alirezarezvani · MIT · alirezarezvani/claude-code-tresor
Similar skills
All skills for Backend and APIs →api-documenter by other authors comes first.