# API Doc Generator

> API Doc Generator

- Skill: `bestdeejay-design/api-doc-generator` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add bestdeejay-design/api-doc-generator`
- Raw SKILL.md: https://api.skillmd.com/api/skills/bestdeejay-design/api-doc-generator/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: bestdeejay-design (https://skillmd.com/u/bestdeejay-design)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/bestdeejay-design/api-doc-generator

---


# API Doc Generator

> Генерация Markdown-документации REST API из OpenAPI-схемы: парсинг схемы,
> разбор endpoint'ов, рендер раздела на каждый метод с параметрами и кодами.

Загружай этот скилл когда нужно **документировать REST API** в Markdown:
по endpoint'ам, с параметрами, телами запросов и кодами ответов. Скилл читает
OpenAPI-схему (JSON) и выдаёт готовый документ.

## 🎯 When to use

Use this skill when:
- Есть `openapi.json`/`swagger.json` и нужен Markdown-документ для README/Wiki
- FastAPI-приложение: нужно отрендерить `app.openapi()` в документацию
- Просят «документация API», «api doc», «описать эндпоинты»
- Нужна автономная страница API Reference без хостинга Swagger UI

Do NOT use when:
- Есть Swagger UI / Redoc онлайн — это уже интерактивная документация
- Нужна сгенерированная из кода схема (Express + swagger-jsdoc) — сначала собери схему, потом этот скрипт
- Нужен глубокий разбор типов (oneOf/allOf) — скрипт выдаёт плоскую таблицу параметров

## 📦 Files

- `SKILL.md` — этот файл
- `scripts/api_doc.py` — рендерер OpenAPI → Markdown (Python 3 stdlib)

## 🧰 Usage

```bash
# Из файла:
python3 skills/api-doc-generator/scripts/api_doc.py --schema openapi.json

# Из stdin:
cat openapi.json | python3 api_doc.py --stdin

# В файл:
python3 api_doc.py --schema openapi.json --title "My API" --out API.md
```

## 🔌 Получение схемы по фреймворку

### FastAPI (OpenAPI 3.1 по умолчанию)
```python
import json, app  # your FastAPI app
with open("openapi.json", "w") as f:
    json.dump(app.openapi(), f, ensure_ascii=False, indent=2)
```
Затем: `python3 api_doc.py --schema openapi.json`.

### Express (Node.js)
Вариант A — swagger-jsdoc (аннотированный код):
```bash
npx swagger-jsdoc -d swagger-def.js -o openapi.json
```
Вариант B — AST-прогулка по маршрутам (если нет аннотаций): собрать
`app._router.stack` (Express 4) в список method+path вручную — базовый случай.

## ✅ Definition of Done
- Скрипт отработал: Markdown-документ в stdout или `--out`.
- Каждый endpoint: method, path, summary, параметры таблицей, коды ответов.
- Схема OpenAPI прошла `json.loads` без ошибок.