Skip to content
Skills Library
Programming · Writing

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".

Repository
skills ↗
Licence
Apache-2.0
Last repository change
25.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
2
Scripts
0
HTML comments
0
URLs in SKILL.md
3
Deprecation

No signals detected. Repository changed on 25.10.2026, without references to retired models or APIs.

Licence

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

write an OpenAPI specdocument my REST APIgenerate a client from openapi.yamllint my swagger file
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

  1. Overview
  2. Instructions
  3. Examples
  4. Guidelines
Original SKILL.md headings · 264 lines, 904 words
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

RepositoryScoreLicence
This page · TerminalSkills/skills100Apache-2.0
khaledsaeed18/dotclaude100MIT

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",…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.