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

# Из файла:
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 без ошибок.