Generate and maintain OpenAPI 3.1 specifications from code, design-first specs, and validation patterns.
From documentationnpx claudepluginhub ccf/claude-code-ccf-marketplace --plugin documentationThis skill uses the workspace's default tool permissions.
templates.mdvalidation.mdFetches up-to-date documentation from Context7 for libraries and frameworks like React, Next.js, Prisma. Use for setup questions, API references, and code examples.
Fetches up-to-date documentation from Context7 for libraries and frameworks like React, Next.js, Prisma. Use for setup questions, API references, and code examples.
Uses ctx7 CLI to fetch current library docs, manage AI coding skills (install/search/generate), and configure Context7 MCP for AI editors.
Patterns for creating and validating OpenAPI 3.1 specifications.
openapi: 3.1.0
info:
title: API Title
version: 1.0.0
servers:
- url: https://api.example.com/v1
paths:
/resources:
get: ...
components:
schemas: ...
securitySchemes: ...
| Approach | Description | Best For |
|---|---|---|
| Design-First | Write spec before code | New APIs, contracts |
| Code-First | Generate spec from code | Existing APIs |
| Hybrid | Annotate code, generate spec | Evolving APIs |
components:
schemas:
User:
type: object
required: [id, email]
properties:
id: { type: string, format: uuid }
email: { type: string, format: email }
parameters:
PageParam:
name: page
in: query
schema: { type: integer, minimum: 1, default: 1 }
responses:
NotFound:
description: Resource not found
content:
application/json:
schema: { $ref: '#/components/schemas/Error' }
components:
securitySchemes:
BearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
ApiKeyAuth:
type: apiKey
in: header
name: X-API-Key
security:
- BearerAuth: []
# Validate spec
npx @stoplight/spectral-cli lint openapi.yaml
# Generate TypeScript client
npx openapi-generator-cli generate \
-i openapi.yaml \
-g typescript-axios \
-o ./generated-client
# Generate server stub
npx openapi-generator-cli generate \
-i openapi.yaml \
-g nodejs-express-server \
-o ./generated-server
/v1/, /v2/ for breaking changesFor detailed templates, see templates.md For validation patterns, see validation.md