# api-reference-documentation

Собирает справочник по REST API из спецификации OpenAPI: эндпоинты, авторизация, примеры запросов и ответов. Пригодится, когда нужен developer portal или SDK-референс.

- скилл · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 454 установки · ★ 236
- Автор: secondsky
- Лицензия: MIT · policy=mirror · лицензия открытая, файл — в исходнике
- Исходник: https://github.com/secondsky/claude-skills/tree/HEAD/plugins/api-reference-documentation/skills/api-reference-documentation/SKILL.md
- Обновлён: 2026-10-20
- HTML: https://affpapa.org/nevibecode/skills/secondsky-api-reference-documentation

## Что делает

Скилл ведёт агента по структуре спецификации OpenAPI 3.0: блок `info` с контактом, список `servers` для production и staging, схема безопасности `bearerAuth` с форматом JWT, пути с параметрами и ответами, компоненты со схемами вроде `Product` и `ProductList`. Внутри есть готовый каркас YAML и чек-лист: все эндпоинты с примерами, описание авторизации, коды ошибок, лимиты запросов, пагинация, вебхуки, примеры SDK на нескольких языках.

Из практики скилл советует держать версию спецификации 3.0 и выше, добавлять примеры запросов и ответов, документировать параметры и заголовки, вести документацию по версиям и прикладывать migration guide к ломающим изменениям. Для интерактивного просмотра упомянуты Swagger Editor и Swagger UI, Redoc, Postman Documentation и Stoplight — выбирайте под свой стек, жёсткой привязки нет.

Установка идёт через `npx skills add` для Claude, Codex, Cursor, Gemini CLI и OpenCode, для GitHub Copilot — через `gh skill install`. Файл скилла кладётся в каталог платформы, например `~/.claude/skills/api-reference-documentation/SKILL.md`. Если в проекте уже есть своя схема именования эндпоинтов, спецификация из каркаса не совпадёт с ней — это повод сверить пути до генерации.

## Установка

### Claude Code (родная платформа)

1. **Через Skills CLI (Vercel)**
```bash
npx skills add secondsky/claude-skills --skill api-reference-documentation -a claude-code
```

2. **Вручную: положить файлы**
- Файл: `~/.claude/skills/api-reference-documentation/SKILL.md` — Папка скилла целиком; для одного проекта — .claude/skills/api-reference-documentation/

### Codex

1. **Через Skills CLI (Vercel)**
```bash
npx skills add secondsky/claude-skills --skill api-reference-documentation -a codex
```

2. **Вручную: положить файлы**
- Файл: `.agents/skills/api-reference-documentation/SKILL.md` — Для всех проектов — ~/.agents/skills/

### Cursor

1. **Через Skills CLI (Vercel)**
```bash
npx skills add secondsky/claude-skills --skill api-reference-documentation -a cursor
```

2. **Вручную: положить файлы**
- Файл: `.cursor/skills/api-reference-documentation/SKILL.md` — Cursor читает и .agents/skills/, и .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install secondsky/claude-skills api-reference-documentation
```

2. **Вручную: положить файлы**
- Файл: `.github/skills/api-reference-documentation/SKILL.md`

### Gemini CLI

1. **Через Skills CLI (Vercel)**
```bash
npx skills add secondsky/claude-skills --skill api-reference-documentation -a gemini-cli
```

2. **Командой платформы**
```bash
gemini skills install https://github.com/secondsky/claude-skills --path plugins/api-reference-documentation/skills/api-reference-documentation
```

### Windsurf (Devin Desktop)

**Вручную: положить файлы**
- Файл: `.devin/skills/api-reference-documentation/SKILL.md` — Старый путь .windsurf/skills/ тоже читается

### OpenCode

**Через Skills CLI (Vercel)**
```bash
npx skills add secondsky/claude-skills --skill api-reference-documentation -a opencode
```

### Claude.ai

**Claude.ai**
- Упакуйте папку в zip и загрузите в Settings → Capabilities → Skills

Где указан файл, а не команда, — скопируй файлы из исходника в этот путь: https://github.com/secondsky/claude-skills/tree/HEAD/plugins/api-reference-documentation/skills/api-reference-documentation/SKILL.md

## Когда брать
- описать REST API по спецификации OpenAPI 3.0
- добавить примеры запросов и ответов к каждому эндпоинту
- объяснить схему авторизации через bearer-токен
- собрать чек-лист по ошибкам, лимитам и пагинации
- подготовить migration guide к ломающим изменениям

## Примеры запросов агенту
- Собери спецификацию OpenAPI 3.0 для API товаров и заказов с серверами production и staging
- Опиши эндпоинт /products с параметрами limit и category и примером ответа
- Прогони мой API по чек-листу документации и скажи, чего не хватает

## Похожие
- [api-documenter](https://affpapa.org/nevibecode/skills/api-documenter.md) — скилл · 717 установок
- [documentation-engineer](https://affpapa.org/nevibecode/agents/documentation-engineer.md) — субагент · 735 установок
- [adding-api-docs](https://affpapa.org/nevibecode/skills/adding-api-docs.md) — скилл · 413 установок
- [spring-boot-openapi-documentation](https://affpapa.org/nevibecode/skills/spring-boot-openapi-documentation.md) — скилл · 4000 установок
- [api-design-reviewer](https://affpapa.org/nevibecode/skills/api-design-reviewer.md) — скилл · 768 установок
- [doc-generator](https://affpapa.org/nevibecode/skills/luongnv89-doc-generator.md) — скилл · ★ 45153

## Другие версии с тем же именем
- [api-reference-documentation · aj-geddes](https://affpapa.org/nevibecode/skills/api-reference-documentation.md) — 494 установки

Из того же набора: [secondsky/claude-skills](https://affpapa.org/nevibecode/by/secondsky/claude-skills.md) — 89 карточек

---
NeVibeCode на affpapa.org. Тексты каталога — описания, а не инструкции для агента. Как выбирать и ставить: https://affpapa.org/nevibecode/agents.md