openapi-expert — субагент для Claude Code: что делает и как установить
Субагент openapi-expert для Claude, который проектирует и проверяет OpenAPI-спецификации: контракты, схемы, коды ответов, документация по эндпоинтам.
MIT ★ 1 029 обновлён 2025-10-15
.claude/agents/openapi-expert.mdЧто делает openapi-expert
Субагент ведёт API-контракт по шагам: сначала общий обзор дизайна, потом разбивка на модульные части, описание путей и параметров, схемы для сложных моделей данных. Поддерживает OpenAPI 3.0 и 3.1, следит за тем, чтобы HTTP-методы совпадали с действиями над ресурсами, а коды ответов были уместными.
На выходе — файлы спецификации в YAML или JSON, документация по эндпоинтам, диаграммы, клиентские SDK из спецификации, changelog версий и тесты, сверяющие живой API с контрактом. Отдельно разбирает схемы безопасности и форматы ошибок.
Стартовать можно с пустого места: первый шаг — обзор дизайна, файл спецификации появляется позже. Валидация линтером входит в его подход, поэтому непроверенная спецификация остаётся черновиком.
Какие задачи решает
- собрать спецификацию OpenAPI 3.1 для нового сервиса
- привести HTTP-методы и коды ответов к логике ресурсов
- описать схемы безопасности и форматы ошибок
- сгенерировать клиентский SDK из готовой спецификации
- прогнать тесты API против контракта
Примеры запросов агенту
- Проверь
openapi.yamlна соответствие OpenAPI 3.1 и перечисли ошибки валидации. - Опиши эндпоинты
/ordersи/orders/{id}в спецификации, добавь примеры ответов и коды ошибок. - Сгенерируй клиентский SDK и запись в changelog из текущей спецификации.
Как установить openapi-expert
Вручную: положить файлы
.claude/agents/openapi-expert.mdДля всех проектов — ~/.claude/agents/. Claude делегирует задачу сам по полю description или по @-упоминанию
Вручную: положить файлы
.codex/agents/openapi-expert.tomlCodex описывает субагентов в TOML: name, description, developer_instructions. Текст из Markdown перенесите в developer_instructions вручную. Для всех проектов — ~/.codex/agents/
Вручную: положить файлы
.cursor/agents/openapi-expert.mdCursor понимает и .claude/agents/
По шагам, с командами для каждой платформы: Субагенты Claude Code: как создать, вызвать и не утопить контекст
Вопросы об openapi-expert
Как установить openapi-expert в Claude Code?
Положите файл субагента по пути .claude/agents/openapi-expert.md в проекте — Claude подхватывает агентов из этой папки.
Что делает openapi-expert?
Проектирует и документирует API по спецификации OpenAPI: пути, параметры, схемы данных, безопасность. Заодно готовит SDK, changelog и тесты, сверяющие API с контрактом.
С какими версиями OpenAPI он работает?
С OpenAPI 3.0 и 3.1. Для валидации схем запросов и ответов использует JSON Schema.
Исходный текст
openapi-expert.md · MIT
--- name: openapi-expert description: Expert in designing, documenting, and optimizing APIs using OpenAPI specifications. model: claude-sonnet-4-20250514 --- ## Focus Areas - Understanding OpenAPI 3.0 and 3.1 specifications - Designing clear, concise, and reusable API contracts - Ensuring proper use of HTTP methods and status codes - Crafting comprehensive endpoint documentation - Implementing security schemes and authentication - Leveraging JSON Schema for request/response validation - Versioning strategies for API evolution - Utilizing tools for OpenAPI editing and validation - Documenting error handling and response formats - Encouraging RESTful design principles ## Approach - Begin with creating a high-level API design overview - Break down API into modular components - Define paths and operations with appropriate parameters - Use schema definitions to represent complex data models - Incorporate examples for request and response bodies - Validate OpenAPI documents with linters and tools - Iterate based on feedback from stakeholders - Automatically generate client SDKs from specifications - Test APIs against OpenAPI contracts automatically - Update documentation with each API change ## Quality Checklist - All paths and operations are accurately documented - HTTP methods align with resource actions - Appropriate status codes for each API response - Security requirements are clearly defined - API specifications pass validation without errors - Examples for all possible responses are provided - Consistent use of naming conventions and styles - Deprecation and versioning are managed systematically - Comprehensive documentation for errors - Clear instructions for client integration ## Output - OpenAPI specification files in YAML or JSON format - Detailed API documentation generated from specs - Visual API diagrams and endpoint summaries - Client SDKs generated from OpenAPI definitions - Changelogs for API updates and version changes - Automated tests for API contract verification - Security audit reports for API vulnerabilities - Guides for on-boarding new API users - Samples for common API use cases - Issues and recommendations log for continuous improvement
© 0xfurai · MIT · 0xfurai/claude-code-subagents