Skip to main content
skill CX Codex

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

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add alirezarezvani/claude-code-tresor --skill api-documenter -a claude-code
Open on GitHub

What 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-code

2Manually: put the files in place

~/.claude/skills/api-documenter/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/api-documenter/

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.

api-documenter zhaono1 api-documenter — a skill for writing REST and GraphQL API documentation as OpenAPI/Swagger specs. Useful when scattered endpoints need to become one readable file. CX Codex +1 727installs code-documenter https://github.com/Jeffallan code-documenter is a Claude Code skill that creates and validates code documentation, API specs, and guides, including docstrings, JSDoc, OpenAPI files, and documentation sites. CX Codex +1 6,200installs api-reference-documentation aj-geddes api-reference-documentation — a skill that walks the agent through writing API reference docs: endpoints, auth, request and response examples, OpenAPI specs. CX Codex +1 501installs doc-api davila7 doc-api is a Claude Code command that generates API documentation directly from source code. It scans project controllers and routes to build OpenAPI specs or interactive Swagger UI. CX Codex +1 733installs hunt-shadow-api Sachin Sharma hunt-shadow-api discovers shadow and zombie API versions by diffing specs and testing behavioral regressions in auth or rate limits. Useful when auditing deprecated endpoints. CX Codex +1 ★ 16,193repo stars api-testing-observability-api-documenter Seth Hobson api-testing-observability-api-documenter — a subagent that writes API documentation: OpenAPI 3.1 specs, interactive examples, SDKs and developer portals. Useful when the API exists but the docs don't. CX Codex ★ 42,780repo stars adding-api-docs spencerpauly The adding-api-docs skill writes OpenAPI/Swagger documentation for an API: endpoint schemas, request and response types, and an interactive docs page. CX Codex +1 455installs

From the same set27

The whole set →
agent agent — a prompt for LLM engineers. Builds and refines prompts across Claude, GPT and open models — from system instructions to reasoning chains, with model-specific adaptation. GP ChatGPT ★ 788repo stars dependency-auditor dependency-auditor is a skill that checks dependencies for vulnerabilities and license issues, then suggests fixes. Run it after dependency file changes or before deployment. CX Codex +1 ★ 788repo stars test-gen test-gen writes test suites against existing code: unit tests for functions, component tests, integration and e2e suites, API tests. Framework and coverage come from flags. CX Codex +1 ★ 788repo stars secret-scanner secret-scanner catches exposed API keys, database credentials, and tokens in code before they leak into git commits. CX Codex +1 ★ 788repo stars readme-updater readme-updater updates README automatically when project structure changes, dependencies are added, or new features land. CX Codex +1 ★ 788repo stars test-generator test-generator produces initial unit test scaffolding for new functions and UI components across popular testing libraries. CX Codex +1 ★ 788repo stars docs-gen The docs-gen command turns a codebase into API docs, guides, and reference material. Use it when you need a documentation site or automated deployment. CX Codex +1 ★ 788repo stars scaffold scaffold writes a project or component skeleton with source files, configs, tests and docs. Flags decide the framework and the extra pieces. CX Codex +1 ★ 788repo stars

Project sponsors

Companies that keep this analytics open