Skip to main content
subagent CX Codex

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

Install into Claude Code · Manually: put the files in place All methods and platforms ↓
.claude/agents/openapi-expert.md
Open on GitHub

What 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.yaml against OpenAPI 3.1 and list every validation error.
  • Add /orders and /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.md

For all projects use ~/.claude/agents/. Claude delegates by the description field or an @-mention

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

Similar subagents

All subagents for Backend and APIs →

From the same set137

The whole set →
actix-expert actix-expert — a Claude Code subagent for Actix and Rust web work, covering routes, middleware, errors, tests, and performance checks. CX Codex ★ 1,029repo stars elixir-expert elixir-expert — an Elixir-focused subagent for Claude: pattern matching, supervision trees, GenServers, Phoenix channels and ExUnit tests, with Dialyzer in the checklist. CX Codex ★ 1,029repo stars grafana-expert grafana-expert designs Grafana dashboards, configures alert rules, and optimizes queries for metrics backends. CX Codex ★ 1,029repo stars opensearch-expert The opensearch-expert subagent helps configure OpenSearch clusters, indexes, and queries. Call on it when working through scaling, security, or performance issues. CX Codex ★ 1,029repo stars kubernetes-expert kubernetes-expert designs Kubernetes manifests, configures cluster autoscaling, and troubleshoots workload issues. Helps prepare container deployments and RBAC policies. CX Codex ★ 1,029repo stars ocaml-expert ocaml-expert — an OCaml subagent for typed functional design, code review, testing, and performance work when a project needs deeper language-specific guidance. CX Codex ★ 1,029repo stars tauri-expert tauri-expert — a Claude subagent for Tauri desktop apps: config files, Rust commands, IPC and the frontend side, plus a checklist to run before release. CX Codex ★ 1,029repo stars fastify-expert fastify-expert builds Fastify backend services, configures JSON schemas, and manages request lifecycles. Useful for structured Node.js API development. CX Codex ★ 1,029repo stars

Project sponsors

Companies that keep this analytics open