К основному содержанию
скилл CX Codex

openapi · itechmeat — скилл для Claude Code: что делает и как установить

Скилл подсказывает ИИ-агенту структуру документов OpenAPI 3.x: обязательные поля, операции, схемы, параметры и безопасность.

MIT 125 установок ★ 23 обновлён 2026-10-24

Установить в Claude Code · Через Skills CLI (Vercel) Все способы и платформы ↓
npx skills add itechmeat/llm-code --skill openapi -a claude-code
Открыть на GitHub

Что делает openapi

Скилл даёт агенту опору по OpenAPI 3.x: обязательные поля документа, объекты info, servers, paths, components, описание операций, параметров и схем безопасности. Внутри — пять справочников в references/: структура документа, операции и пути, схемы и типы, параметры с сериализацией, безопасность.

Примеры рабочие: объект User с format: uuid, композиция через allOf, полиморфизм через oneOf с discriminator, nullable через массив типов из OAS 3.1+. Таблица разводит расположения параметров (path, query, header, cookie, querystring) и стили (simple, form, matrix, label, deepObject). Версия спецификации здесь 3.2.0, и на ней легко спутать два поля: openapi в шапке — это версия OAS, а версия самого API живёт в info.version. Второе поле обязательное.

Ставится одной командой npx skills add, внутри текстовые справочники рядом с SKILL.md. operationId у каждой операции свой: на нём держится генерация клиента или сервера из спеки, дубли её сбивают.

Какие задачи решает

  • написать спеку с нуля по структуре OAS 3.x
  • развести параметры по path, query и header
  • описать OAuth2 или API-ключ в securitySchemes
  • собрать модель ответа из allOf и oneOf
  • проверить готовый документ перед генерацией клиента

Примеры запросов агенту

  • Опиши эндпоинт GET /users/{id} в спеке OpenAPI 3.2 и добавь ответ 404.
  • Проверь мой openapi.yaml: обязательные поля на месте, схемы безопасности описаны?
  • Сделай Pet через oneOf с discriminator по полю petType.

Как установить openapi

1Через Skills CLI (Vercel)

npx skills add itechmeat/llm-code --skill openapi -a claude-code

2Вручную: положить файлы

~/.claude/skills/openapi/SKILL.md

Папка скилла целиком; для одного проекта — .claude/skills/openapi/

По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов

Вопросы об openapi

Как установить openapi в Claude Code?

Выполните npx skills add itechmeat/llm-code --skill openapi -a claude-code. Скилл окажется в ~/.claude/skills/openapi/SKILL.md.

Что делает скилл openapi?

Подкладывает агенту справочники по OAS 3.x: структура документа, операции, схемы, параметры, безопасность. По ним он пишет и проверяет спеки, не додумывая имена полей.

Чем openapi в шапке отличается от info.version?

openapi задаёт версию самой спецификации, здесь 3.2.0. info.version — версия вашего API, и это обязательное поле.

Исходный текст

SKILL.md · MIT
---
name: openapi
description: "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."
metadata:
  version: "3.2.1"
  release_date: "2026-09-10"
---

# 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

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

### Complete Structure

```yaml
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

```yaml
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: [email protected]
  license:
    name: Apache 2.0
    identifier: Apache-2.0 # OR url (mutually exclusive)
```

### Server Object

```yaml
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

```yaml
/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

```yaml
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

```yaml
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

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

### Polymorphism with oneOf

```yaml
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

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

## Parameter Locations

| Location     | `in` value    | Notes                               |
| ------------ | ------------- | ----------------------------------- |
| Path         | `path`        | MUST be required: true              |
| Query        | `query`       | Standard query parameters           |
| Query string | `querystring` | Entire query string as single param |
| Header       | `header`      | Case-insensitive names              |
| Cookie       | `cookie`      | Cookie values                       |

### Parameter Styles

| Style      | `in`  | Type                   | Example (color=blue,black) |
| ---------- | ----- | ---------------------- | -------------------------- |
| simple     | path  | array                  | blue,black                 |
| form       | query | primitive/array/object | color=blue,black           |
| matrix     | path  | primitive/array/object | ;color=blue,black          |
| label      | path  | primitive/array/object | .blue.black                |
| deepObject | query | object                 | color[R]=100&color[G]=200  |

## Security Schemes

### API Key

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

### Bearer Token (JWT)

```yaml
bearerAuth:
  type: http
  scheme: bearer
  bearerFormat: JWT
```

### OAuth2

```yaml
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

```yaml
# 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:

```yaml
# 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:

```yaml
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

| Error                      | Fix                                                   |
| -------------------------- | ----------------------------------------------------- |
| Missing required field     | Add `openapi`, `info.title`, `info.version`           |
| Invalid operationId        | Use unique, valid identifier                          |
| Path parameter not in path | Ensure `{param}` matches parameter name               |
| Duplicate path template    | Remove conflicting `/users/{id}` vs `/users/{userId}` |
| Invalid $ref               | Check URI syntax and target existence                 |

## Links

- [Documentation](https://spec.openapis.org/oas/latest.html)
- [Releases](https://github.com/OAI/OpenAPI-Specification/releases)
- [GitHub](https://github.com/OAI/OpenAPI-Specification)
- [Learning Portal](https://learn.openapis.org/)

© itechmeat · MIT · itechmeat/llm-code

Похожие скиллы

Все скиллы по теме «Бэкенд и API» →

Сначала — openapi от других авторов.

openapi codewithmukesh Настраивает встроенную генерацию спецификаций OpenAPI в .NET 10 без Swashbuckle. Помогает агенту писать трансформеры, метаданные и схемы безопасности. CX Codex +1 4 000установок openapi oakoss Настраивает агента на проектирование спецификаций OpenAPI 3.1 и генерацию TypeScript-клиентов. Помогает писать схемы контрактов и документацию для REST API. CX Codex +1 197установок openapi finom Скилл объясняет, как Vovk.ts собирает спецификацию OpenAPI из процедур и схем валидации. Пригодится, чтобы описать API и показать его документацию через Scalar. CX Codex +1 ★ 57звёзд репо route-to-openapi zebbern Скилл route-to-openapi для Claude Code, сканирует маршруты в коде и собирает спецификацию OpenAPI 3.0.3. Автоматизирует генерацию документации API из определений эндпоинтов. CX Codex +1 ★ 4 719звёзд репо spring-boot-openapi-documentation giuseppe-trisciuoglio Скилл spring-boot-openapi-documentation помогает агенту настроить SpringDoc OpenAPI 3.0 и Swagger UI в проекте на Spring Boot 3.x и разметить эндпоинты аннотациями. CX Codex +1 4 200установок openapi-expert personamanagmentlayer Скилл openapi-expert проектирует спецификации OpenAPI 3.0 и 3.1, настраивает полиморфизм схем и генерирует код клиентов или серверов. CX Codex +1 282установок openapi-spec-writer curiositech Скилл openapi-spec-writer проектирует спецификации OpenAPI 3.0 и 3.1 для REST API. Помогает составить схемы данных и настроить документацию ещё до написания серверного кода. CX Codex +1 175установок api-documenter zhaono1 Скилл api-documenter для Claude Code: описывает REST и GraphQL API в формате OpenAPI/Swagger. Превращает россыпь эндпоинтов в читаемую спецификацию. CX Codex +1 727установок api-reference-documentation secondsky Скилл api-reference-documentation для Claude Code и других платформ собирает справочник по REST API из спецификации OpenAPI: эндпоинты, авторизация, примеры запросов и ответов. Закрывает задачи developer portal и SDK-референса. CX Codex +1 472установок

Из того же набора16

Весь набор →
changelog Скилл задаёт структуру CHANGELOG.md по Keep a Changelog 1.1.0: разделы Added/Changed/Fixed, заголовки версий, даты ISO 8601 и ссылки на сравнения. CX Codex +1 192установок makefile Помогает агенту создавать и поддерживать Makefile: правила, переменные, рецепты, проверки и сборку. Автоматизирует команды проекта. CX Codex +1 181установок commits Помогает агенту оформлять Git-коммиты по Conventional Commits с учётом breaking changes. Формат используют для changelog и SemVer. CX Codex +1 178установок skill-master Скилл skill-master для Claude и других агентов: помогает писать, проверять и сравнивать Agent Skills по спецификации agentskills.io — от структуры папок до замеров срабатывания. CX Codex +1 161установок project-creator Скилл project-creator разворачивает структуру технической документации в папке .project/ и ведёт интервью, по шагам создавая спецификации, архитектуру и пользовательские истории. CX Codex +1 113установок vite Скилл помогает агенту настраивать и использовать Vite: от dev-сервера и сборки до плагинов, HMR и переменных окружения. CX Codex +1 111установок fastapi Помогает создавать Python API на FastAPI. Он включается при работе с REST-маршрутами, Pydantic-моделями, зависимостями и OAuth2/JWT. CX Codex +1 100установок open-meteo Помогает запрашивать прогноз погоды, качество воздуха и координаты мест через Open-Meteo. Включается при работе с почасовыми, дневными или текущими показателями. CX Codex +1 100установок

Спонсоры проекта

Компании, которые помогают держать аналитику открытой