MCPInstall

openapi

by itechmeatBackend & APIs

OpenAPI Specification (OAS 3.x): document structure, paths, operations, schemas, parameters, security schemes, and validation. Use when writing, reading, or validating OpenAPI specs, designing REST API schemas, or working with OAS 3.x document structure. Keywords: OpenAPI, OAS, Swagger, REST API, schemas.

Installs
122
Last 24h
—
Trending rank
—
Security
Not audited

Install

Works with every agent the skills CLI supports.

npx skills add https://github.com/itechmeat/llm-code --skill openapi
  1. 01

    Install

    Run the command in your project. The CLI asks which agents to install for.

  2. 02

    Describe the task

    Ask your agent for something this skill covers. It loads openapi automatically when relevant.

  3. 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 Specification

This skill provides guidance for working with OpenAPI Specification (OAS) documents.

Current version: OpenAPI 3.2.0 (September 2025)

Quick Navigation

  • Document structure: references/document-structure.md
  • Operations & paths: references/operations.md
  • Schemas & data types: references/schemas.md
  • Parameters & serialization: references/parameters.md
  • Security: references/security.md

When to Use

  • Creating a new OpenAPI specification document
  • Describing HTTP API endpoints
  • Defining request/response schemas
  • Configuring API security (OAuth2, API keys, JWT)
  • Validating an existing OpenAPI document
  • Generating client/server code from specs

Document Structure Overview

An OpenAPI document MUST have either an OpenAPI Object or Schema Object at the root.

Required Fields

openapi: 3.2.0 # REQUIRED: OAS version
info: # REQUIRED: API metadata
  title: My API
  version: 1.0.0

Complete Structure

openapi: 3.2.0
info:
  title: Example API
  version: 1.0.0
  description: API description (supports CommonMark)
servers:
  - url: https://api.example.com/v1
paths:
  /resources:
    get:
      summary: List resources
      responses:
        "200":
          description: Success
components:
  schemas: {}
  parameters: {}
  responses: {}
  securitySchemes: {}
security:
  - apiKey: []
tags:
  - name: resources
    description: Resource operations

Core Objects Reference

Info Object

info:
  title: Example API # REQUIRED
  version: 1.0.0 # REQUIRED (API version, NOT OAS version)
  summary: Short summary
  description: Full description (CommonMark)
  termsOfService: https://example.com/terms
  contact:
    name: API Support
    url: https://example.com/support
    email: support@example.com
  license:
    name: Apache 2.0
    identifier: Apache-2.0 # OR url (mutually exclusive)

Server Object

servers:
  - url: https://api.example.com/v1
    description: Production
  - url: https://{environment}.example.com:{port}/v1
    description: Configurable
    variables:
      environment:
        default: api
        enum: [api, staging, dev]
      port:
        default: "443"

Path Item Object

/users/{id}:
  summary: User operations
  parameters:
    - $ref: "#/components/parameters/userId"
  get:
    operationId: getUser
    responses:
      "200":
        description: User found
  put:
    operationId: updateUser
    requestBody:
      $ref: "#/components/requestBodies/UserUpdate"
    responses:
      "200":
        description: User updated

Operation Object

get:
  tags: [users]
  summary: Get user by ID
  description: Returns a single user
  operationId: getUserById # MUST be unique across all operations
  parameters:
    - name: id
      in: path
      required: true
      schema:
        type: string
  responses:
    "200":
      description: Success
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/User"
    "404":
      description: Not found
  security:
    - bearerAuth: []
  deprecated: false

Schema Recipes

Basic Object

components:
  schemas:
    User:
      type: object
      required: [id, email]
      properties:
        id:
          type: string
          format: uuid
        email:
          type: string
          format: email
        name:
          type: string
        age:
          type: integer
          minimum: 0

Composition with allOf

ExtendedUser:
  allOf:
    - $ref: "#/components/schemas/User"
    - type: object
      properties:
        role:
          type: string
          enum: [admin, user, guest]

Polymorphism with oneOf

Pet:
  oneOf:
    - $ref: "#/components/schemas/Cat"
    - $ref: "#/components/schemas/Dog"
  discriminator:
    propertyName: petType
    mapping:
      cat: "#/components/schemas/Cat"
      dog: "#/components/schemas/Dog"

Nullable and Optional

# OAS 3.1+ uses JSON Schema type arrays
properties:
  nickname:
    type: [string, "null"] # nullable

Parameter Locations

Locationin valueNotes
PathpathMUST be required: true
QueryqueryStandard query parameters
Query stringquerystringEntire query string as single param
HeaderheaderCase-insensitive names
CookiecookieCookie values

Parameter Styles

StyleinTypeExample (color=blue,black)
simplepatharrayblue,black
formqueryprimitive/array/objectcolor=blue,black
matrixpathprimitive/array/object;color=blue,black
labelpathprimitive/array/object.blue.black
deepObjectqueryobjectcolor[R]=100&color[G]=200

Security Schemes

API Key

components:
  securitySchemes:
    apiKey:
      type: apiKey
      in: header # header, query, or cookie
      name: X-API-Key

Bearer Token (JWT)

bearerAuth:
  type: http
  scheme: bearer
  bearerFormat: JWT

OAuth2

oauth2:
  type: oauth2
  flows:
    authorizationCode:
      authorizationUrl: https://auth.example.com/authorize
      tokenUrl: https://auth.example.com/token
      scopes:
        read:users: Read user data
        write:users: Modify user data

Apply Security

# Global (all operations)
security:
  - bearerAuth: []

# Per-operation
paths:
  /public:
    get:
      security: [] # Override: no auth required
  /protected:
    get:
      security:
        - oauth2: [read:users]

Reference Object

Use $ref to avoid duplication:

# Reference within same document
$ref: '#/components/schemas/User'

# Reference to external file
$ref: './schemas/user.yaml'
$ref: './common.yaml#/components/schemas/Error'

Components Object

Reusable building blocks:

components:
  schemas: # Data models
  responses: # Reusable responses
  parameters: # Reusable parameters
  examples: # Reusable examples
  requestBodies: # Reusable request bodies
  headers: # Reusable headers
  securitySchemes: # Security definitions
  links: # Links between operations
  callbacks: # Webhook definitions
  pathItems: # Reusable path items

Best Practices Checklist

  • Include operationId for all operations (unique, programming-friendly)
  • Use $ref for reusable components
  • Add meaningful description fields (supports CommonMark)
  • Define all possible response codes
  • Include examples for complex schemas
  • Use tags to group related operations
  • Mark deprecated operations with deprecated: true
  • Use semantic versioning for info.version

Critical Prohibitions

  • Do NOT omit openapi and info fields (they are REQUIRED)
  • Do NOT use duplicate operationId values
  • Do NOT mix $ref with sibling properties in Reference Objects
  • Do NOT use path parameters without required: true
  • Do NOT use implicit OAuth2 flow in new APIs (deprecated)
  • Do NOT forget security for protected endpoints

Validation

File Naming

  • Entry document: openapi.json or openapi.yaml (recommended)
  • Format: JSON or YAML (equivalent)
  • All field names are case-sensitive

Common Validation Errors

ErrorFix
Missing required fieldAdd openapi, info.title, info.version
Invalid operationIdUse unique, valid identifier
Path parameter not in pathEnsure {param} matches parameter name
Duplicate path templateRemove conflicting /users/{id} vs /users/{userId}
Invalid $refCheck URI syntax and target existence

Links

FAQ

What does the openapi skill do?

OpenAPI Specification (OAS 3.x): document structure, paths, operations, schemas, parameters, security schemes, and validation. Use when writing, reading, or validating OpenAPI specs, designing REST API schemas, or working with OAS 3.x document structure. Keywords: OpenAPI, OAS, Swagger, REST API, schemas.

How do I install openapi?

Run npx skills add https://github.com/itechmeat/llm-code --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 itechmeat in itechmeat/llm-code. It has 122 recorded installs.

More from itechmeat/llm-code

View all →

react-testing-library

itechmeat/llm-code

React Testing Library: user-centric component testing with queries, user-event simulation, async utilities, and accessibility-first API. Use when writing React component tests, selecting elements by role/label/text, simulating user events, or testing async UI behavior. Keywords: React Testing Library, @testing-library/react, user-event, queries, render.

Frontend & Design1.4K installs

openspec

itechmeat/llm-code

OpenSpec artifact-driven workflow. Covers OPSX commands, schemas, project config. Use when applying the artifact-driven workflow (OPSX), planning or reviewing changes based on artifact dependencies, or working with OPSX commands and schema/template resolution. Keywords: OPSX, artifact graph, /opsx:.

Productivity & Automation840 installs

mantine-dev

itechmeat/llm-code

Open the skill to read its SKILL.md instructions.

AI & Agents286 installs

social-writer

itechmeat/llm-code

Open the skill to read its SKILL.md instructions.

Docs & Writing265 installs

base-ui

itechmeat/llm-code

Open the skill to read its SKILL.md instructions.

Frontend & Design228 installs

refine-dev

itechmeat/llm-code

Open the skill to read its SKILL.md instructions.

AI & Agents206 installs

Popular backend & apis skills

View category →

find-skills

vercel-labs/skills

Helps users discover and install agent skills when they ask questions like "how do I do X", "find a skill for X", "is there a skill that can...", or express interest in extending capabilities. This skill should be used when the user is looking for functionality that might exist as an installable skill.

OfficialBackend & APIs4.1M installs

entra-app-registration

microsoft/azure-skills

Guides Microsoft Entra ID app registration, OAuth 2.0 authentication, and MSAL integration. USE FOR: create app registration, register Azure AD app, configure OAuth, set up authentication, add API permissions, generate service principal, MSAL example, console app auth, Entra ID setup, Azure AD authentication. DO NOT USE FOR: Key Vault secrets (use azure-keyvault-expiration-audit), general Azure resource security guidance.

OfficialBackend & APIs566.7K installs

google-agents-cli-adk-code

google/agents-cli

This skill should be used when the user wants to "write agent code", "build an agent with ADK", "add a tool", "create a callback", "define an agent", "use state management" — in a project that needs ADK (Agent Development Kit) API patterns and code examples. It provides a quick reference for agent types, tool definitions, orchestration patterns, callbacks, state management, the graph Workflow API, and reference recipes to study. Do NOT use for scaffolding (use google-agents-cli-scaffold) or deployment (use google-agents-cli-deploy).

Backend & APIs514.8K installs

embedded-captions

heygen-com/hyperframes

Add captions or subtitles to an existing single-subject talking-head video without editing the footage. Use for plain verbatim captions, cinematic captions embedded behind the subject, VFX captions, “炸/特效/酷炫字幕,” or a named identity from the 35-style catalog. Route by visual identity, not by backend engine. The quiet anchor rail is the default; embed every word only when the user explicitly wants a fully cinematic treatment. The workflow runs locally end to end, including transcription and subject matting; split multi-shot footage before applying it.

Backend & APIs453.3K installs

entra-agent-id

microsoft/azure-skills

Provision Microsoft Entra Agent Identity Blueprints, BlueprintPrincipals, and per-instance Agent Identities via Microsoft Graph, and configure OAuth 2.0 token exchange (fmipath, OBO, cross-tenant) including the Microsoft Entra SDK for AgentID sidecar. USE FOR: Agent Identity Blueprint, BlueprintPrincipal, agent OAuth, fmipath token exchange, agent OBO, Workload Identity Federation for agents, polyglot agent auth, Microsoft.Identity.Web.AgentIdentities. DO NOT USE FOR: standard Entra app registration (use entra-app-registration), Microsoft Foundry agent authoring (use microsoft-foundry).

OfficialBackend & APIs336.6K installs

neon

neondatabase/agent-skills

Overview of Neon, a complete set of cloud backend primitives around Lakebase Postgres: Auth, Object Storage, Functions, the AI Gateway, and Realtime. Start here to choose Neon for undecided login, files, APIs, and LLM calls, set up the CLI or MCP server, and follow the branch-first workflow. Use when building an app or backend on Neon, or when "Neon" or "Lakebase Postgres" is mentioned. Child skill neon-postgres wins for an existing DATABASEURL, SQL, schema, inspect, or search. Child skill neon-auth wins for login, users, sessions, identity routing, and Managed Better Auth setup. Child skill neon-realtime wins for live queries in reactive apps and agents. Also use for object storage, S3, buckets, serverless functions, function triggers, cron, AI gateway, LLM calls, realtime, logs, Loki, Grafana, observability, postgres, database, backend, Claimable Neon, neon.new, or a no-signup database.

Backend & APIs237.1K installs