openapi

Q: How do I install openapi?

Run npx skills add https://github.com/oakoss/agent-skills --skill openapi in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/openapi/ (personal) or .claude/skills/openapi/ (project).

by oakossBackend & APIs

OpenAPI 3.1 specification, schema design, and code generation. Use when designing REST APIs, generating TypeScript clients, or creating API documentation. Use for openapi, swagger, api-spec, schema, code-generation, api-docs, openapi-typescript, zod-openapi.

Installs: 187
Last 24h: —
Trending rank: —
Security: Not audited

Install

Works with every agent the skills CLI supports.

npx skills add https://github.com/oakoss/agent-skills --skill openapi

01
Install
Run the command in your project. The CLI asks which agents to install for.
02
Describe the task
Ask your agent for something this skill covers. It loads openapi automatically when relevant.
03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.

SKILL.md

The instructions your agent reads when the skill is triggered.

OpenAPI

Overview

OpenAPI Specification (OAS) 3.1 is the industry standard for describing HTTP APIs. It defines a machine-readable contract covering endpoints, request/response schemas, authentication, and error formats. OpenAPI 3.1 is a strict superset of JSON Schema Draft 2020-12, enabling full JSON Schema compatibility for data validation and type generation.

When to use: Designing REST APIs, generating typed clients (TypeScript, Python, Go), producing interactive documentation, validating request/response payloads, contract-first API development, API gateway configuration.

When NOT to use: GraphQL APIs (use the GraphQL schema), gRPC services (use Protocol Buffers), WebSocket-only protocols, internal function calls that never cross a network boundary.

Quick Reference

Pattern	Element	Key Points
Document root	`openapi`, `info`, `paths`	`openapi: '3.1.0'` required at top level
Path item	`/resources/{id}`	Curly braces for path parameters
Operation	`get`, `post`, `put`, `delete`, `patch`	Each operation needs `operationId` and `responses`
Parameters	`in: path\|query\|header\|cookie`	Path params are always `required: true`
Request body	`requestBody.content`	Keyed by media type (`application/json`)
Response	`responses.200.content`	At least one response required per operation
Component ref	`$ref: '#/components/schemas/Name'`	Reuse schemas, parameters, responses
Schema types	`type: string\|number\|integer\|boolean\|array\|object`	Arrays support `type: ["string", "null"]` in 3.1
Composition	`oneOf`, `anyOf`, `allOf`	Model polymorphism and intersection types
Discriminator	`discriminator.propertyName`	Hint for code generators with `oneOf`/`anyOf`
Security	`securitySchemes` + top-level `security`	Bearer, API key, OAuth2, OpenID Connect
Tags	`tags` on operations	Group operations for documentation
Type generation	`openapi-typescript`	Zero-runtime TypeScript types from spec
Typed fetch	`openapi-fetch`	Type-safe HTTP client using generated types
React Query	`openapi-react-query`	Type-safe React Query hooks from spec
Schema-first	`zod-openapi`	Generate OpenAPI documents from Zod schemas

Common Mistakes

Mistake	Correct Pattern
Using `nullable: true` in 3.1	Use `type: ["string", "null"]` (3.0 syntax removed)
Missing `operationId` on operations	Always set unique `operationId` for code generation
Path parameter not in `required`	Path parameters are always required (`required: true`)
Inline schemas everywhere	Extract to `components/schemas` and use `$ref`
`allOf` with conflicting `required` fields	Merge `required` arrays; `allOf` unions them
Discriminator without shared property	All schemas in `oneOf`/`anyOf` must include the discriminator property
Empty `description` on responses	Every response needs a meaningful `description`
Using `type: object` without `properties`	Always define `properties` or use `additionalProperties`
Circular `$ref` chains	Break cycles with lazy resolution or restructure schemas
Mixing 3.0 and 3.1 syntax	Choose one version; 3.1 drops `nullable`, changes `exclusiveMinimum` to number

Delegation

API design review: Use Task agent to audit spec completeness and consistency
Type generation: Use Explore agent to find project-specific OpenAPI tooling config
Code review: Delegate to code-reviewer agent for generated client usage patterns

If the typescript-patterns skill is available, delegate advanced TypeScript typing questions to it.

References

Schema design: paths, operations, parameters, components, and $ref
Data types: formats, composition, discriminators, and nullable
Code generation: openapi-typescript, openapi-fetch, openapi-react-query, and Zod OpenAPI
Documentation: Swagger UI, Redoc, and API docs best practices

FAQ

What does the openapi skill do?

How do I install openapi?

Run npx skills add https://github.com/oakoss/agent-skills --skill openapi in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/openapi/ (personal) or .claude/skills/openapi/ (project).

Which AI agents can use openapi?

Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.

Is openapi safe to install?

No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.

Who maintains openapi?

It is published by oakoss in oakoss/agent-skills. It has 187 recorded installs.

More from oakoss/agent-skills

View all →

ui-ux-polish

oakoss/agent-skills

Iterative UI/UX polishing workflow for web applications. Use when improving visual polish, refining desktop and mobile UX separately, running iterative enhancement cycles, applying design patterns like glassmorphism or bento grids, or auditing accessibility and WCAG compliance. Use for Stripe-level visual quality, responsive optimization, and design system alignment.

Frontend & Design541 installs