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

# Из файла:
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 по умолчанию)

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 (аннотированный код):

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 без ошибок.

Boundaries

• Do not use for validating whether an API matches its contract; use api-contract-testing for checks.

Operating procedure

1. Load the OpenAPI 3.x document and fail if it is not parseable.
2. Preserve the source operation order and group methods by path.
3. Render parameters, request bodies, response codes, auth hints, and operation IDs without inventing values.
4. Write to the requested output path, then reopen the result and verify every source operation has a corresponding Markdown heading.

Output contract and verification

The output is Markdown plus a run summary containing the input path, operation count, output path, and exit status. Treat missing schemas, unresolved references, and unsupported constructs as explicit warnings; never silently omit an endpoint. Re-run the generator after changing the spec and compare the operation count before claiming completeness.