К основному содержанию
скилл CX Codex

api-documenter · alirezarezvani — скилл для Claude Code: API-документация

Скилл api-documenter для Claude Code собирает спецификации API по коду и комментариям. Формирует документацию при изменении маршрутов или подготовке OpenAPI-документа.

MIT ★ 788 обновлён 2026-07-03

Установить в Claude Code · Через Skills CLI (Vercel) Все способы и платформы ↓
npx skills add alirezarezvani/claude-code-tresor --skill api-documenter -a claude-code
Открыть на GitHub

Что делает api-documenter

Скилл анализирует маршруты и комментарии, затем формирует документацию API. Он умеет создавать спецификации OpenAPI 3.0 и Swagger 2.0, а также материалы в форматах API Blueprint и RAML. В документацию могут войти схемы запросов и ответов, требования авторизации, примеры и ошибки.

Скилл распознаёт Express.js, FastAPI, Django REST, Spring Boot, Gin и Rails. Он извлекает сведения из JSDoc, Python docstrings, JavaDoc и комментариев с декораторами; доступные инструменты — Read, Write и Grep. Созданную OpenAPI-спецификацию можно использовать со Swagger UI или импортировать в Postman. Скилл пишет файлы на диск, но сетевой доступ ему не нужен.

Он работает и с включённой песочницей, и без неё. Описания следуют за кодом, поэтому устаревшие комментарии приведут к устаревшей документации. Для пользовательских руководств в исходнике предлагается отдельный субагент @docs-writer.

Какие задачи решает

  • собрать OpenAPI-спецификацию по маршрутам проекта
  • описать параметры и ответы API по комментариям в коде
  • добавить примеры запросов и типовые ошибки в документацию
  • подготовить спецификацию для импорта в Postman

Примеры запросов агенту

  • Составь OpenAPI-спецификацию для новых маршрутов проекта.
  • Обнови документацию API после изменений в контроллерах.
  • Подготовь спецификацию, которую можно импортировать в Postman.

Как установить api-documenter

1Через Skills CLI (Vercel)

npx skills add alirezarezvani/claude-code-tresor --skill api-documenter -a claude-code

2Вручную: положить файлы

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

Папка скилла целиком; для одного проекта — .claude/skills/api-documenter/

По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов

Вопросы об api-documenter

Как установить api-documenter в Claude Code?

Выполните npx skills add alirezarezvani/claude-code-tresor --skill api-documenter -a claude-code, затем используйте файл ~/.claude/skills/api-documenter/SKILL.md.

Что делает api-documenter?

Он создаёт спецификации API на основе маршрутов и комментариев в коде. Поддерживает OpenAPI 3.0, Swagger 2.0, API Blueprint и RAML.

Какие фреймворки распознаёт api-documenter?

Скилл распознаёт Express.js, FastAPI, Django REST, Spring Boot, Gin и Rails. Для извлечения описаний использует, среди прочего, JSDoc, Python docstrings и JavaDoc.

Исходный текст

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

Похожие скиллы

Все скиллы по теме «Бэкенд и API» →

Сначала — api-documenter от других авторов.

api-documenter zhaono1 Скилл api-documenter для Claude Code: описывает REST и GraphQL API в формате OpenAPI/Swagger. Превращает россыпь эндпоинтов в читаемую спецификацию. CX Codex +1 727установок code-documenter https://github.com/Jeffallan Скилл code-documenter создаёт и проверяет документацию к коду, API и руководства. Нужен при добавлении docstring, JSDoc или спецификации OpenAPI. CX Codex +1 6 200установок api-reference-documentation aj-geddes Скилл api-reference-documentation помогает агенту собрать справочник по API: эндпоинты, аутентификация, примеры запросов и ответов, спецификация OpenAPI. CX Codex +1 501установок doc-api davila7 Команда doc-api для Claude Code генерирует документацию API по кодовой базе проекта. Она находит маршруты, контроллеры и схемы данных, формируя спецификации OpenAPI или интерактивный Swagger UI. CX Codex +1 733установок hunt-shadow-api Sachin Sharma Скилл hunt-shadow-api находит забытые и теневые версии API, сравнивая спецификации и проверяя регрессии в аутентификации и лимитах. Пригодится при аудите устаревших эндпоинтов. CX Codex +1 ★ 16 193звёзд репо api-testing-observability-api-documenter Seth Hobson Субагент api-testing-observability-api-documenter для Claude Code пишет документацию API: спецификации OpenAPI 3.1, интерактивные примеры, SDK и порталы для разработчиков. Описывает API, для которого ещё нет документации. CX Codex ★ 42 780звёзд репо adding-api-docs spencerpauly Скилл adding-api-docs собирает OpenAPI/Swagger-описание вашего API: схемы эндпоинтов, типы запросов и ответов, интерактивную страницу документации. CX Codex +1 455установок

Из того же набора27

Весь набор →
agent Промпт agent для инженера LLM-систем. Помогает писать и улучшать промпты для Claude, GPT и открытых моделей — от системных инструкций до chain-of-thought цепочек. GP ChatGPT ★ 788звёзд репо dependency-auditor Скилл dependency-auditor проверяет зависимости на уязвимости и проблемы с лицензиями, а затем предлагает варианты исправления. Запускайте проверку после изменений в файлах зависимостей или перед деплоем. CX Codex +1 ★ 788звёзд репо test-gen Команда test-gen пишет тесты к готовому коду: юнит-тесты функций, компонентные, интеграционные, e2e и тесты API. Фреймворк и порог покрытия задаются флагами. CX Codex +1 ★ 788звёзд репо secret-scanner Скилл secret-scanner находит случайно вписанные пароли, токены и приватные ключи в коде до того, как они попадут в коммит или репозиторий. CX Codex +1 ★ 788звёзд репо readme-updater Скилл readme-updater обновляет README автоматически, когда меняется структура проекта, добавляются зависимости или новые фичи. CX Codex +1 ★ 788звёзд репо test-generator Скилл test-generator генерирует базовые заготовки тестов для новых функций и React-компонентов под популярные тест-раннеры. CX Codex +1 ★ 788звёзд репо docs-gen Команда docs-gen анализирует кодовую базу и собирает API-документацию, руководства и справочные материалы. Подходит для генерации сайта документации и автодеплоя. CX Codex +1 ★ 788звёзд репо scaffold Команда scaffold генерирует каркас проекта или отдельного компонента: исходники, конфиги, тесты и документацию. Фреймворк и набор фич задаются флагами. CX Codex +1 ★ 788звёзд репо

Спонсоры проекта

Компании, которые помогают держать аналитику открытой