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

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

Скилл openapi-expert проектирует спецификации OpenAPI 3.0 и 3.1, настраивает полиморфизм схем и генерирует код клиентов или серверов.

Apache-2.0 282 установок ★ 45 обновлён 2026-10-12

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

Что делает openapi-expert

Скилл помогает составлять контракты API в форматах YAML и JSON. Он ориентируется на версии OpenAPI 3.0 и 3.1, подсказывает синтаксис вебхуков и описывает полиморфные модели данных через oneOf, anyOf, allOf и discriminator.

В инструкциях заложены готовые сценарии работы со сторонними утилитами. Агент умеет вызывать кодогенератор @openapitools/openapi-generator-cli для сборки клиентов на TypeScript или серверов на Python и Java, проверять контракты линтером Spectral и поднимать контейнеры Swagger UI или Redoc.

Для автоматического запуска линтера или кодогенерации в терминале понадобятся глобально установленные пакеты Node.js либо Docker.

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

  • описать вебхуки и контракты эндпоинтов по стандарту OpenAPI 3.1
  • собрать клиентскую библиотеку на TypeScript через openapi-generator-cli
  • проверить готовый YAML-контракт линтером Spectral
  • сконфигурировать полиморфные схемы с селектором discriminator

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

  • Опиши схему вебхука postCreated в формате OpenAPI 3.1 с телом Post
  • Сгенерируй TypeScript-клиент по файлу openapi.yaml через openapi-generator-cli
  • Настрой файл .spectral.yaml для проверки operationId и тегов в спецификации

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

1Через Skills CLI (Vercel)

npx skills add personamanagmentlayer/pcl --skill openapi-expert -a claude-code

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

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

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

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

Вопросы об openapi-expert

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

Выполните в терминале команду npx skills add personamanagmentlayer/pcl --skill openapi-expert -a claude-code. Файл навыка сохранится по пути ~/.claude/skills/openapi-expert/SKILL.md.

Что делает openapi-expert?

Он задаёт модели контекст по правилам OpenAPI 3.0 и 3.1, позволяя проектировать контракты REST API, генерировать клиенты и настраивать валидацию.

Какие внешние инструменты использует этот скилл?

Инструкции ориентированы на @openapitools/openapi-generator-cli для кодогенерации, Spectral для статического анализа спецификаций и образы Swagger UI или Redoc в Docker.

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

SKILL.md · Apache-2.0
---
name: openapi-expert
version: 1.1.0
description: >-
  Expert-level OpenAPI/Swagger specification for API design, documentation, and code
  generation. Use when the user mentions swagger, API specs, REST, API design, or
  documentation, or when the task involves OpenAPI Specification, Webhooks, or
  Polymorphism.
category: api
tags: [openapi, swagger, api-spec, rest, api-design, documentation]
allowed-tools:
  - Read
  - Write
  - Edit
  - Bash(openapi:*, swagger:*)
---

# OpenAPI Expert

Expert guidance for OpenAPI Specification (formerly Swagger) - industry-standard for describing RESTful APIs with automatic documentation and code generation.

## Core Concepts

### OpenAPI Specification (OAS)

- API description format (YAML/JSON)
- Version 3.1 (latest) and 3.0
- Machine-readable API contracts
- Automatic documentation generation
- Client/server code generation
- API validation and testing

### Key Components

- Paths (endpoints)
- Operations (HTTP methods)
- Parameters
- Request/Response bodies
- Schemas (data models)
- Security schemes
- Components (reusable objects)

## Advanced Features

### Webhooks (OpenAPI 3.1)

```yaml
webhooks:
  postCreated:
    post:
      summary: Post created webhook
      operationId: onPostCreated
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Post'
      responses:
        '200':
          description: Webhook received
```

### Polymorphism (oneOf/anyOf/allOf)

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

    Cat:
      allOf:
        - $ref: '#/components/schemas/PetBase'
        - type: object
          properties:
            petType:
              type: string
              enum: [cat]
            meow:
              type: string

    Dog:
      allOf:
        - $ref: '#/components/schemas/PetBase'
        - type: object
          properties:
            petType:
              type: string
              enum: [dog]
            bark:
              type: string
```

## Code Generation

```bash
# Install OpenAPI Generator
npm install -g @openapitools/openapi-generator-cli

# Generate TypeScript client
openapi-generator-cli generate \
  -i openapi.yaml \
  -g typescript-axios \
  -o ./client

# Generate Python Flask server
openapi-generator-cli generate \
  -i openapi.yaml \
  -g python-flask \
  -o ./server

# Generate Java Spring server
openapi-generator-cli generate \
  -i openapi.yaml \
  -g spring \
  -o ./server
```

## Validation

```bash
# Install Spectral (OpenAPI linter)
npm install -g @stoplight/spectral-cli

# Validate spec
spectral lint openapi.yaml

# Custom ruleset
# .spectral.yaml
extends: spectral:oas
rules:
  operation-tags: error
  operation-operationId: error
  no-$ref-siblings: error
```

## Documentation Generation

```bash
# Swagger UI
docker run -p 8080:8080 \
  -e SWAGGER_JSON=/openapi.yaml \
  -v $(pwd):/usr/share/nginx/html \
  swaggerapi/swagger-ui

# Redoc
docker run -p 8080:80 \
  -e SPEC_URL=openapi.yaml \
  -v $(pwd):/usr/share/nginx/html \
  redocly/redoc
```

## Best Practices

- Use semantic versioning
- Include examples in schemas
- Provide clear descriptions
- Use components for reusability
- Define proper error responses
- Include security schemes
- Add operation IDs
- Tag operations logically
- Validate specifications
- Version your APIs

## Reference Documentation

Detailed material lives alongside this skill and is read on demand:

- [Basic OpenAPI Specification](references/BASIC_OPENAPI_SPECIFICATION.md)

## Resources

- OpenAPI Spec: https://spec.openapis.org/
- Swagger Editor: https://editor.swagger.io/
- OpenAPI Tools: https://openapi.tools/
- Stoplight Studio: https://stoplight.io/studio

© personamanagmentlayer · Apache-2.0 · personamanagmentlayer/pcl

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

Все скиллы по теме «Бэкенд и API» →
openapi-spec-writer curiositech Скилл openapi-spec-writer проектирует спецификации OpenAPI 3.0 и 3.1 для REST API. Помогает составить схемы данных и настроить документацию ещё до написания серверного кода. CX Codex +1 175установок 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 oakoss Настраивает агента на проектирование спецификаций OpenAPI 3.1 и генерацию TypeScript-клиентов. Помогает писать схемы контрактов и документацию для REST API. CX Codex +1 197установок api-design-reviewer borghei Скилл api-design-reviewer для Claude Code проверяет спецификации OpenAPI, находит несовместимые изменения между версиями и оценивает зрелость контракта REST API. CX Codex +1 167установок go-openapi eduardo-sl Скилл go-openapi настраивает подход spec-first для REST API на Go: генерирует интерфейсы через oapi-codegen, подключает middleware валидации и отслеживает ломающие изменения схемы. CX Codex +1 ★ 90звёзд репо openapi-generator patricio0312rev Скилл openapi-generator для Claude Code, Codex, Cursor и других ИИ-редакторов генерирует спецификации OpenAPI 3.0/3.1 прямо из маршрутов Express, Next.js, Fastify, Hono или NestJS. CX Codex +1 320установок

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

Весь набор →
hospitality-expert Скилл hospitality-expert по гостиничному хозяйству: помогает агенту разобраться с PMS, бронированиями, тарифами и запросами гостей. CX Codex +1 298установок blockchain-expert Скилл blockchain-expert для Claude Code разбирает блокчейн, Web3, Solidity, смарт-контракты и DeFi. Помогает проектировать, тестировать и аудировать криптосистемы. CX Codex +1 296установок farming-expert Скилл farming-expert даёт агенту агрономический контекст: севооборот, показания почвенных датчиков, NDVI и прогноз урожайности, с примерами кода на Python. CX Codex +1 283установок energy-expert Скилл energy-expert для Claude Code помогает с задачами по энергосистемам, умным сетям и SCADA. Подключается к запросам о возобновляемой энергетике, управлении мощностью и энергетической аналитике. CX Codex +1 282установок git-expert Скилл git-expert для Claude Code даёт агенту рецепты для git: отмены коммита, извлечения работы из main и чистки истории. Разбирает проблемы с git, возникшие посреди работы. CX Codex +1 279установок python-expert Скилл python-expert настраивает ИИ-ассистента на разработку на современном Python: строгая типизация, стандарты PEP 8, асинхронный код, работа с uv, poetry и ruff. CX Codex +1 277установок redis-expert Скилл redis-expert для Claude Code помогает проектировать Redis-кэш, pub/sub и работу с потоками данных. Помогает добавлять Redis в приложение и разбирать его архитектуру. CX Codex +1 272установок php-expert Скилл php-expert для Claude Code задаёт агенту правила работы с PHP 8+, Laravel, Composer и PHPUnit. Охватывает разработку, тестирование и ревью современного PHP-кода. CX Codex +1 269установок

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

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