# Api Doc Generator

> Генерация Markdown-документации REST API из OpenAPI-схемы (3.x, включая 3.1.0). Скрипт api_doc.py читает openapi.json (файл или stdin), извлекает endpoint'ы (method, path, summary, operationId, параметры query/path/header, requestBody, коды ответов) и рендерит Markdown-раздел на каждый эндпоинт. FastAPI: схема из app.openapi() или /openapi.json; Express: swagger-jsdoc (референс в SKILL.md). Тригг…

- **Type:** Skill
- **Install:** `agentstack add skill-bestdeejay-design-agent-skills-api-doc-generator`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [bestdeejay-design](https://agentstack.voostack.com/s/bestdeejay-design)
- **Installs:** 0
- **Category:** [Developer Tools](https://agentstack.voostack.com/c/developer-tools)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [bestdeejay-design](https://github.com/bestdeejay-design)
- **Source:** https://github.com/bestdeejay-design/agent-skills/tree/main/skills/api-doc-generator
- **Website:** https://bestdeejay-design.github.io/agent-skills/

## Install

```sh
agentstack add skill-bestdeejay-design-agent-skills-api-doc-generator
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

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

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [bestdeejay-design](https://github.com/bestdeejay-design)
- **Source:** [bestdeejay-design/agent-skills](https://github.com/bestdeejay-design/agent-skills)
- **License:** MIT
- **Homepage:** https://bestdeejay-design.github.io/agent-skills/

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-bestdeejay-design-agent-skills-api-doc-generator
- Seller: https://agentstack.voostack.com/s/bestdeejay-design
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.