openapi-expert — Claude Code subagent: what it does, how to install
openapi-expert — a Claude subagent that writes and checks OpenAPI specs: contracts, schemas, status codes and endpoint documentation.
MIT ★ 1,029 updated 2025-10-15
.claude/agents/openapi-expert.mdWhat openapi-expert does
The subagent walks an API contract through stages. It opens with a design overview, splits the API into modular pieces, then spells out paths, parameters and schemas for the data models. OpenAPI 3.0 and 3.1 are both in scope.
What comes back: spec files in YAML or JSON, endpoint docs, diagrams, client SDKs built from the spec, a changelog per version and tests that check the running API against the contract. Security schemes and error formats get their own pass.
You can start from nothing: the first step is a design overview, the spec file follows later. Linting is part of the workflow, so a spec nobody validated is still a draft.
What it helps with
- draft an OpenAPI 3.1 spec for a new service
- line up HTTP methods and status codes with resource actions
- document security schemes and error responses
- generate a client SDK from an existing spec
- run contract tests against a live API
Example prompts for the agent
- Check
openapi.yamlagainst OpenAPI 3.1 and list every validation error. - Add
/ordersand/orders/{id}to the spec with sample responses and error codes. - Generate the client SDK and a changelog entry from the current spec.
How to install openapi-expert
Manually: put the files in place
.claude/agents/openapi-expert.mdFor all projects use ~/.claude/agents/. Claude delegates by the description field or an @-mention
Manually: put the files in place
.codex/agents/openapi-expert.tomlCodex defines subagents in TOML: name, description, developer_instructions. Move the Markdown text into developer_instructions by hand. For all projects use ~/.codex/agents/
Manually: put the files in place
.cursor/agents/openapi-expert.mdCursor also reads .claude/agents/
Step by step, with commands for each platform: Claude Code subagents: how to create one, call it and keep context clean
Questions about openapi-expert
How do I install openapi-expert in Claude Code?
Drop the agent file at .claude/agents/openapi-expert.md inside your project. Claude reads subagents from that folder.
What does openapi-expert do?
It designs and documents an API through its OpenAPI spec: paths, parameters, data schemas, security. It also produces SDKs, a changelog and tests that compare the API with the contract.
Which OpenAPI versions does it handle?
OpenAPI 3.0 and 3.1. Request and response validation runs through JSON Schema.
Source text
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