Этот навык помогает разработчикам создавать профессиональную документацию API со спецификациями OpenAPI, интерактивным Swagger UI, примерами кода и справочными руководствами для REST и GraphQL API.
Скачать ZIP навыка
Загрузить в Claude
Перейдите в Settings → Capabilities → Skills → Upload skill
Включите и начните использовать
Протестировать
Использование «api-documentation». Создать спецификацию OpenAPI для API управления пользователями
Ожидаемый результат:
Полная спецификация OpenAPI 3.0 с конечной точкой /users, нумерацией страниц, аутентификацией и схемами ответов
Использование «api-documentation». Документировать поток аутентификации
Ожидаемый результат:
Пошаговое руководство: 1. Конечная точка входа возвращает JWT, 2. Включите токен Bearer в заголовок Authorization, 3. Механизм обновления токена, 4. Примеры команд curl
Использование «api-documentation». Определить структуру справочника API
Ожидаемый результат:
Организованная документация с: Обзор, Аутентификация, Конечные точки, сгруппированные по ресурсам, Коды ошибок, Ограничение скорости, Журнал изменений
Аудит безопасности
БезопасноAll 79 static findings are false positives. The skill contains only documentation templates with example URLs and code blocks. No actual shell commands, network exfiltration, or cryptographic vulnerabilities exist. The scanner triggered on markdown code delimiters, placeholder URLs in examples, and JWT authentication mentions in OpenAPI specs.
Оценка качества
Что вы можете построить
Разработка внутреннего API
Документирование API внутренних микросервисов для совместной работы команд frontend и backend
Выпуск публичного API
Создание профессиональной документации для внешних разработчиков, использующих ваш API
Документация SDK
Создание комплексных руководств и справочной документации для потребителей библиотек
Попробуйте эти промпты
Create an OpenAPI 3.0 specification for a REST API endpoint that manages users. Include GET (list), POST (create), GET by ID, PUT (update), DELETE endpoints. Define request/response schemas with proper HTTP status codes.
Document a protected API endpoint that requires JWT authentication. Include the auth flow, bearer token usage, 401/403 error responses, and example curl commands for authenticated requests.
Create a comprehensive error handling guide for a REST API. Document all common error codes (400, 401, 403, 404, 409, 429, 500), their meanings, example error responses, and recommended client handling approaches.
Set up Swagger UI for an Express.js API. Show how to integrate swagger-ui-express, load an OpenAPI YAML file, configure custom CSS, and mount the docs at /api-docs.
Лучшие практики
- Предоставляйте рабочие примеры кода на нескольких языках (JavaScript, Python, curl)
- Всегда документируйте как успешные, так и ошибочные случаи с примерами
- Поддерживайте синхронизацию документации с изменениями API с помощью журналов изменений
Избегать
- Использование реальных ключей API или паролей в примерах кода
- Использование расплывчатых описаний типа «возвращает данные» без уточнений
- Отсутствие документации об ошибочных случаях для сценариев сбоя
Часто задаваемые вопросы
Какую версию OpenAPI поддерживает этот навык?
Могу ли я создать документацию для GraphQL API?
Как настроить интерактивный Swagger UI?
Какие методы аутентификации поддерживаются?
Может ли этот навык тестировать мои фактические конечные точки API?
Как документировать ограничение скорости?
Сведения для разработчиков
Автор
supercent-ioЛицензия
MIT
Репозиторий
https://github.com/supercent-io/skills-template/tree/main/.agent-skills/api-documentation/Ссылка
main
Структура файлов
📄 SKILL.md