openapi-spec
/openapi-spec
OpenAPI is the standard format for describing HTTP APIs in YAML or JSON, from which docs, typed clients and mock servers can be generated. Use this skill to write an OpenAPI 3.1 spec, lint it with Redocly CLI, generate TypeScript types and a typed fetch client, build HTML docs, and keep a spec valid. Use when someone says "write an OpenAPI spec", "document my REST API", "generate a client from openapi.yaml" or "lint my swagger file".
- Author
- TerminalSkills ↗
- Repository
- skills ↗
- Licence
- Apache-2.0
- Last repository change
- 25.10.2026
Assessment and security
- Files in this package
- 2
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 3
No signals detected. Repository changed on 25.10.2026, without references to retired models or APIs.
Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.
What it does and when to use it
OpenAPI is the standard format for describing HTTP APIs in YAML or JSON, from which docs, typed clients and mock servers can be generated. Use this skill to write an OpenAPI 3.1 spec, lint it with Redocly CLI, generate TypeScript types and a typed fetch client, build HTML docs, and keep a spec valid. Use when someone says "write an OpenAPI spec", "document my REST API", "generate a client from openapi.yaml" or "lint my swagger file".
Triggers from the description
Original author description
OpenAPI is the standard format for describing HTTP APIs in YAML or JSON, from which docs, typed clients and mock servers can be generated. Use this skill to write an OpenAPI 3.1 spec, lint it with Redocly CLI, generate TypeScript types and a typed fetch client, build HTML docs, and keep a spec valid. Use when someone says "write an OpenAPI spec", "document my REST API", "generate a client from openapi.yaml" or "lint my swagger file".
How it works
- Overview
- Instructions
- Examples
- Guidelines
SKILL.md preview
---
name: openapi-spec
description: >-
OpenAPI is the standard format for describing HTTP APIs in YAML or JSON, from which docs, typed clients and mock servers can be generated. Use this skill to write an OpenAPI 3.1 spec, lint it with Redocly CLI, generate TypeScript types and a typed fetch client, build HTML docs, and keep a spec valid. Use when someone says "write an OpenAPI spec", "document my REST API", "generate a client from openapi.yaml" or "lint my swagger file".
license: Apache-2.0
compatibility: 'Node.js 20.19+ or 22.12+ for the Redocly CLI (2.x), Node.js 20+ for openapi-typescript; spec is language-agnostic'
metadata:
author: terminal-skills
version: 1.1.0
category: development
repository: https://github.com/OAI/OpenAPI-Specification
tags: "openapi, swagger, api-design, documentation, rest"
---
# OpenAPI Specification
## Overview
An OpenAPI document describes an HTTP API: paths, operations, parameters, request and response bodies, and security. This skill targets OpenAPI 3.1 (JSON Schema 2020-12 compatible). Versions 3.2.0 and 3.2.1 also exist; 3.1 is still the version most tooling supports fully, so check your tools before moving. Design-first means the spec is written and reviewed before code, and later drives docs, SDKs and contract tests.
Tool versions checked in October 2026: `@redocly/cli` 2.71, `openapi-typescript` 7.13, `openapi-fetch` 0.17.
## Instructions
### Step 1: Write the spec
Save as `openapi.yaml`. Notes on what the example does:
- `security` at the root applies to every operation; the two public GET operations opt out with `security: []`.
- In 3.1, "may be null" is written `type: [string, 'null']`. The 3.0 keyword `nullable: true` is invalid in 3.1 and Redocly rejects it.
- `examples` (a list) replaces the old singular `example` on schemas.
- Every operation has at least one 4XX response, and shared errors live in `components/responses`.
```yaml
openapi: 3.1.0
info:
title: Project Management API
version: 1.0.0
description: API for managing projects and tasks
license:
name: Apache-2.0
identifier: Apache-2.0
servers:
- url: https://api.acmeprojects.dev/v1
description: Production
security:
- bearerAuth: []
paths:
/projects:
get:
summary: List projects
operationId: listProjects
tags: [Projects]
security: []
parameters:
- name: status
in: query
schema:
type: string
enum: [active, archived, all]
default: active
- name: limit
in: query
schema:
type: integer
minimum: 1
maximum: 100
default: 20
- name: cursor
in: query
description: Pagination cursor from the previous response
schema:
type: string
responses:
'200':
description: List of projects
content:
application/json:
schema:
type: object
required: [data, nextCursor]
properties:
data:
type: array
items:
$ref: '#/components/schemas/Project'
nextCursor:
type: [string, 'null']
'400':
$ref: '#/components/responses/ValidationError'
post:
summary: Create a project
operationId: createProject
tags: [Projects]
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateProjectInput'
responses:
'201':
description: Project created
content:
application/json:
schema:
$ref: '#/components/schemas/Project'
'401':
$ref: '#/components/responses/Unauthorized'
'422':
$ref: '#/components/responses/ValidationError'
/projects/{projectId}:
get:
summary: Get a project by ID
operationId: getProject
tags: [Projects]
security: []
parameters:
- name: projectId
in: path
required: true
schema:
type: string
format: uuid
responses:
'200':
description: Project details
content:
application/json:
schema:
$ref: '#/components/schemas/Project'
'404':
$ref: '#/components/responses/NotFound'
components:
schemas:
Project:
type: object
required: [id, name, status, createdAt]
properties:
id:
type: string
format: uuid
name:
type: string
examples: ["Website Redesign"]
description:
type: [string, 'null']
status:
type: string
enum: [active, archived]
taskCount:
type: integer
createdAt:
type: string
format: date-time
CreateProjectInput:
type: object
required: [name]
properties:
name:
type: string
minLength: 1
maxLength: 100
description:
type: string
maxLength: 500
Error:
type: object
required: [error]
properties:
error:
type: string
details:
type: array
items:
type: object
properties:
field:
type: string
message:
type: string
responses:
NotFound:
description: Resource not found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
ValidationError:
description: Validation error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
Unauthorized:
description: Missing or invalid bearer token
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
```
### Step 2: Lint
```bash
npx @redocly/cli lint openapi.yaml
```
Exit code is non-zero on errors, so this works as a CI gate. Rules are configured in `redocly.yaml` (`extends: [recommended]`, then per-rule `error`/`warn`/`off`). Redocly CLI 2.x no longer has `preview-docs`; build static docs instead:
```bash
npx @redocly/cli build-docs openapi.yaml -o docs/index.html
```
For specs split over several files, `npx @redocly/cli bundle openapi.yaml -o dist/openapi.yaml` resolves all `$ref`s into one file.
### Step 3: Generate TypeScript types and a typed client
```bash
npm install --save-dev openapi-typescript typescript
npm install openapi-fetch
npx openapi-typescript openapi.yaml -o src/api/schema.d.ts
```
```typescript
import createClient from "openapi-fetch";
import type { paths, components } from "./schema";
type Project = components["schemas"]["Project"];
const client = createClient<paths>({ baseUrl: "https://api.acmeprojects.dev/v1" });
const { data, error } = await client.GET("/projects", {
params: { query: { status: "active", limit: 20 } },
});
if (error) throw new Error(error.error); // typed as the Error schema
const projects: Project[] = data.data;
const created = await client.POST("/projects", {
body: { name: "Website Redesign" },
headers: { Authorization: `Bearer ${process.env.PROJECTS_API_TOKEN}` },
});
```
Path, query and body types are checked at compile time against the spec; rerun `openapi-typescript` whenever it changes. Add `--check` in CI to fail if the committed file is stale.
## Examples
### Example 1: "Add an endpoint to archive a project"
Add `/projects/{projectId}/archive` with `post`, `operationId: archiveProject`, path parameter `projectId`, a `200` returning `Project`, plus `401` and `404` via `$ref`. Run `npx @redocly/cli lint openapi.yaml`; the output ends with `Woohoo! Your API description is valid.` Regenerate types and `client.POST("/projects/{projectId}/archive", { params: { path: { projectId } } })` becomes available.
### Example 2: "The linter says `Property nullable is not expected here`"
The spec declares `openapi: 3.1.0` but uses 3.0 syntax. Replace `type: string` + `nullable: true` with `type: [string, 'null']`, and `example:` with `examples: [...]`. Re-run lint; the errors disappear.
## Guidelines
- Design-first: agree the spec in review before implementing; it is cheaper to change YAML than code.
- Give every operation a unique `operationId`; generators use it for method names.
- Reuse with `$ref` for schemas, error responses and parameters.
- Declare security once at the root and opt out per operation, so a new endpoint is protected by default.
- Match the `openapi:` version to the syntax you use (3.0 and 3.1 differ in nullability, `exclusiveMinimum`, `example` and `webhooks`).
- Version breaking changes in the URL (`/v1`) and keep `info.version` for the spec's own revisions; diff specs in CI before releasing.
- Treat example values in the spec as public documentation: no real tokens or customer data.
Files in this package (2)
- SKILL.md 9 KB
- _scores.json 2 KB
Versions
| Repository | Score | Licence |
|---|---|---|
| This page · TerminalSkills/skills | 100 | Apache-2.0 |
| khaledsaeed18/dotclaude | 100 | MIT |
Database snapshot: 13.11.2026 · package version 1ee7a2f284fa (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100api-docs
Write reference documentation or an OpenAPI spec for a REST/HTTP API by reading its source code. Use when the user says "document the API", "write endpoint docs", "generate an OpenAPI/Swagger spec", "what endpoints do we have", or "document this route". - 100openapi
Use when documenting APIs — OpenAPI/Swagger, PHP attributes, Redocly validation, versioned specs — even when the user just says 'document this endpoint' without naming OpenAPI. - 100openapi-generate
Generate OpenAPI 3.1 specs from existing code (routes, controllers, types, Zod/Joi schemas), or generate code from an existing spec. Produces valid openapi.yaml, typed client SDKs, mock servers, and Postman collections. Use when documenting an API, onboarding clients, generating… - 100openapi-typesafe
Generate TypeScript types from an OpenAPI 3.x document with openapi-typesafe and call the API through openapi-typesafe-fetch or openapi-typesafe-react-query with fully inferred types. Use when a project depends on openapi-typesafe, openapi-typesafe-fetch or… - 100openapi-to-typescript
Converts OpenAPI 3.0 JSON/YAML to TypeScript interfaces and type guards. This skill should be used when the user asks to generate types from OpenAPI, convert schema to TS, create API interfaces, or generate TypeScript types from an API specification. - 100openapi-codegen
OpenAPI client code generation. Covers openapi-typescript, openapi-generator-cli, swagger-typescript-api, and trpc-openapi. Use for generating type-safe API clients. USE WHEN: user mentions "OpenAPI codegen", "generate API client", "openapi-typescript", "swagger-typescript-api",…