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

openapi-spec-writer — скилл для Claude Code: обзор и установка

Скилл openapi-spec-writer проектирует спецификации OpenAPI 3.0 и 3.1 для REST API. Помогает составить схемы данных и настроить документацию ещё до написания серверного кода.

MIT 175 установок ★ 274 обновлён 2026-10-30

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

Что делает openapi-spec-writer

Скилл генерирует спецификации REST API в форматах OpenAPI 3.0 и 3.1. Он описывает маршруты, коды ответов, параметры запросов и структуры моделей на базе JSON Schema. Для сложных сущностей используются дискриминаторы полиморфизма, а также композиции oneOf, anyOf и allOf. В спецификацию сразу добавляются реалистичные примеры полезной нагрузки, описания ошибок и отметки устаревших методов.

Помимо описания эндпоинтов, скилл настраивает экосистему вокруг контракта. Он готовит конфигурации для Swagger UI и Redoc, создаёт мок-серверы и формирует правила линтинга через Spectral. Без строгой типизации полей Spectral сразу выдаст ошибку валидации схемы.

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

  • описать контракты REST API в формате OpenAPI 3.0 или 3.1
  • добавить схемы валидации параметров и тел запросов через JSON Schema
  • перенести старую спецификацию Swagger 2.0 на версию 3.x
  • настроить правила Spectral и документацию для Swagger UI или Redoc

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

  • Спроектируй спецификацию OpenAPI 3.1 для сервиса задач с Bearer-авторизацией
  • Опиши схему ответа с пагинацией и фильтрами по статусу для эндпоинта GET /tasks
  • Сконвертируй старый файл Swagger 2.0 в формат OpenAPI 3.0 с примерами ошибок

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

1Через Skills CLI (Vercel)

npx skills add curiositech/some_claude_skills --skill openapi-spec-writer -a claude-code

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

~/.claude/skills/openapi-spec-writer/SKILL.md

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

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

Вопросы об openapi-spec-writer

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

Выполните команду npx skills add curiositech/some_claude_skills --skill openapi-spec-writer -a claude-code.

Какие версии OpenAPI поддерживает скилл?

Он работает с синтаксисом OpenAPI 3.0 и 3.1, а также помогает мигрировать со старых версий Swagger 2.0.

Поможет ли скилл с инструментами вроде Swagger UI или Spectral?

Да, в его задачи входит настройка конфигурации для Swagger UI, Redoc, мок-серверов и правил линтинга Spectral.

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

SKILL.md · MIT
---
name: openapi-spec-writer
description: Expert in writing OpenAPI 3.0/3.1 specifications for REST APIs. Specializes in schema design, documentation best practices, API-first development, and tooling integration. Generates comprehensive
  API documentation that serves as both documentation and contract.
version: 1.0.0
metadata:
  category: documentation
  tags:
  - openapi
  - swagger
  - api-documentation
  - rest
  - api-design
  pairs-with:
  - skill: api-architect
    reason: API design decisions are formalized and documented through OpenAPI specifications
  - skill: rest-api-design
    reason: REST endpoint design and OpenAPI documentation are tightly coupled deliverables
  - skill: technical-writer
    reason: API documentation quality depends on technical writing clarity and completeness
---

# OpenAPI Spec Writer

## Overview

Expert in writing OpenAPI 3.0/3.1 specifications for REST APIs. Specializes in schema design, documentation best practices, API-first development, and tooling integration. Generates comprehensive API documentation that serves as both documentation and contract.

## When to Use

- Creating OpenAPI specifications for new APIs
- Documenting existing REST APIs
- Designing API contracts before implementation
- Generating client SDKs from specs
- Setting up interactive API documentation (Swagger UI, Redoc)
- Validating API responses against schemas
- Migrating from OpenAPI 2.0 (Swagger) to 3.x

## Capabilities

### Specification Writing
- OpenAPI 3.0 and 3.1 syntax
- Path and operation definitions
- Request/response schemas
- Authentication schemes
- Server configurations

### Schema Design
- JSON Schema with OpenAPI extensions
- Reusable component schemas
- Discriminators for polymorphism
- oneOf, anyOf, allOf composition
- Nullable types and defaults

### Documentation Quality
- Meaningful descriptions and examples
- Markdown in descriptions
- Request/response examples
- Error response documentation
- Deprecation notices

### Tooling Integration
- Swagger UI configuration
- Redoc customization
- Spectral linting rules
- SDK generation setup
- Mock server configuration

## Dependencies

Works well with:
- `api-architect` - API design patterns
- `rest-api-design` - RESTful conventions
- `typescript-pro` - Generated client types
- `github-actions-pipeline-builder` - CI validation

## Examples

### Complete OpenAPI 3.1 Spec
```yaml
openapi: 3.1.0
info:
  title: Task Management API
  description: |
    RESTful API for managing tasks and projects.

    ## Authentication
    All endpoints require a Bearer token in the Authorization header.

    ## Rate Limiting
    - 1000 requests per hour per API key
    - Rate limit headers included in all responses
  version: 1.0.0
  contact:
    name: API Support
    email: [email protected]
    url: https://docs.example.com
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT

servers:
  - url: https://api.example.com/v1
    description: Production server
  - url: https://staging-api.example.com/v1
    description: Staging server
  - url: http://localhost:3000/v1
    description: Local development

tags:
  - name: Tasks
    description: Task management operations
  - name: Projects
    description: Project management operations

paths:
  /tasks:
    get:
      operationId: listTasks
      summary: List all tasks
      description: Returns a paginated list of tasks with optional filtering.
      tags:
        - Tasks
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/LimitParam'
        - name: status
          in: query
          description: Filter by task status
          schema:
            $ref: '#/components/schemas/TaskStatus'
        - name: project_id
          in: query
          description: Filter by project ID
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaskListResponse'
              examples:
                default:
                  $ref: '#/components/examples/TaskListExample'
          headers:
            X-Total-Count:
              schema:
                type: integer
              description: Total number of tasks matching the query
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'

    post:
      operationId: createTask
      summary: Create a new task
      description: Creates a new task and returns the created resource.
      tags:
        - Tasks
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateTaskRequest'
            examples:
              minimal:
                summary: Minimal task
                value:
                  title: "Complete documentation"
              full:
                summary: Full task with all fields
                value:
                  title: "Complete documentation"
                  description: "Write API docs for v1.0"
                  project_id: "550e8400-e29b-41d4-a716-446655440000"
                  due_date: "2024-12-31"
                  priority: "high"
      responses:
        '201':
          description: Task created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Task'
          headers:
            Location:
              schema:
                type: string
                format: uri
              description: URL of the created resource
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'

  /tasks/{taskId}:
    parameters:
      - $ref: '#/components/parameters/TaskIdParam'

    get:
      operationId: getTask
      summary: Get a task by ID
      tags:
        - Tasks
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Task'
        '404':
          $ref: '#/components/responses/NotFound'

    patch:
      operationId: updateTask
      summary: Update a task
      description: Partially updates a task. Only provided fields are updated.
      tags:
        - Tasks
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateTaskRequest'
      responses:
        '200':
          description: Task updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Task'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/ValidationError'

    delete:
      operationId: deleteTask
      summary: Delete a task
      tags:
        - Tasks
      responses:
        '204':
          description: Task deleted successfully
        '404':
          $ref: '#/components/responses/NotFound'

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT token obtained from /auth/login

  parameters:
    TaskIdParam:
      name: taskId
      in: path
      required: true
      description: Unique task identifier
      schema:
        type: string
        format: uuid
      example: "550e8400-e29b-41d4-a716-446655440000"

    PageParam:
      name: page
      in: query
      description: Page number for pagination (1-indexed)
      schema:
        type: integer
        minimum: 1
        default: 1

    LimitParam:
      name: limit
      in: query
      description: Number of items per page
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 20

  schemas:
    Task:
      type: object
      required:
        - id
        - title
        - status
        - created_at
        - updated_at
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier
          readOnly: true
        title:
          type: string
          minLength: 1
          maxLength: 200
          description: Task title
        description:
          type: string
          maxLength: 5000
          description: Detailed task description (supports Markdown)
        status:
          $ref: '#/components/schemas/TaskStatus'
        priority:
          $ref: '#/components/schemas/Priority'
        project_id:
          type: string
          format: uuid
          description: Associated project ID
        due_date:
          type: string
          format: date
          description: Due date (ISO 8601)
        created_at:
          type: string
          format: date-time
          readOnly: true
        updated_at:
          type: string
          format: date-time
          readOnly: true

    TaskStatus:
      type: string
      enum:
        - pending
        - in_progress
        - completed
        - cancelled
      description: Current task status
      default: pending

    Priority:
      type: string
      enum:
        - low
        - medium
        - high
        - urgent
      default: medium

    CreateTaskRequest:
      type: object
      required:
        - title
      properties:
        title:
          type: string
          minLength: 1
          maxLength: 200
        description:
          type: string
          maxLength: 5000
        project_id:
          type: string
          format: uuid
        due_date:
          type: string
          format: date
        priority:
          $ref: '#/components/schemas/Priority'

    UpdateTaskRequest:
      type: object
      minProperties: 1
      properties:
        title:
          type: string
          minLength: 1
          maxLength: 200
        description:
          type: string
          maxLength: 5000
        status:
          $ref: '#/components/schemas/TaskStatus'
        priority:
          $ref: '#/components/schemas/Priority'
        due_date:
          type: string
          format: date

    TaskListResponse:
      type: object
      required:
        - data
        - pagination
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Task'
        pagination:
          $ref: '#/components/schemas/Pagination'

    Pagination:
      type: object
      required:
        - page
        - limit
        - total
        - total_pages
      properties:
        page:
          type: integer
        limit:
          type: integer
        total:
          type: integer
        total_pages:
          type: integer
        has_next:
          type: boolean
        has_prev:
          type: boolean

    Error:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: string
          description: Machine-readable error code
        message:
          type: string
          description: Human-readable error message
        details:
          type: object
          additionalProperties: true
          description: Additional error details

    ValidationError:
      allOf:
        - $ref: '#/components/schemas/Error'
        - type: object
          properties:
            errors:
              type: array
              items:
                type: object
                properties:
                  field:
                    type: string
                  message:
                    type: string

  responses:
    BadRequest:
      description: Bad request - invalid parameters
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: "BAD_REQUEST"
            message: "Invalid query parameters"

    Unauthorized:
      description: Authentication required
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: "UNAUTHORIZED"
            message: "Invalid or expired token"

    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: "NOT_FOUND"
            message: "Task not found"

    ValidationError:
      description: Validation failed
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ValidationError'
          example:
            code: "VALIDATION_ERROR"
            message: "Request validation failed"
            errors:
              - field: "title"
                message: "Title is required"

  examples:
    TaskListExample:
      value:
        data:
          - id: "550e8400-e29b-41d4-a716-446655440000"
            title: "Complete documentation"
            status: "in_progress"
            priority: "high"
            created_at: "2024-01-15T10:30:00Z"
            updated_at: "2024-01-15T10:30:00Z"
        pagination:
          page: 1
          limit: 20
          total: 42
          total_pages: 3
          has_next: true
          has_prev: false

security:
  - bearerAuth: []
```

### Polymorphic Schemas (Discriminator)
```yaml
components:
  schemas:
    Notification:
      type: object
      required:
        - id
        - type
        - created_at
      discriminator:
        propertyName: type
        mapping:
          email: '#/components/schemas/EmailNotification'
          sms: '#/components/schemas/SmsNotification'
          push: '#/components/schemas/PushNotification'
      properties:
        id:
          type: string
          format: uuid
        type:
          type: string
          enum: [email, sms, push]
        created_at:
          type: string
          format: date-time

    EmailNotification:
      allOf:
        - $ref: '#/components/schemas/Notification'
        - type: object
          required:
            - to
            - subject
          properties:
            to:
              type: string
              format: email
            subject:
              type: string
            body:
              type: string

    SmsNotification:
      allOf:
        - $ref: '#/components/schemas/Notification'
        - type: object
          required:
            - phone_number
            - message
          properties:
            phone_number:
              type: string
              pattern: '^\+[1-9]\d{1,14}$'
            message:
              type: string
              maxLength: 160
```

### Spectral Linting Rules
```yaml
# .spectral.yaml
extends: ["spectral:oas"]

rules:
  # Enforce operation IDs
  operation-operationId: error

  # Require descriptions
  operation-description: error
  oas3-schema-description: warn

  # Naming conventions
  path-casing:
    given: "$.paths[*]~"
    then:
      function: casing
      functionOptions:
        type: kebab

  # Security requirements
  operation-security-defined: error

  # Response codes
  operation-success-response: error

  # Custom: require examples
  require-examples:
    message: "Responses should have examples"
    given: "$.paths.*.*.responses.*.content.*.schema"
    then:
      field: example
      function: truthy
```

## Best Practices

1. **Use components** - Extract reusable schemas, parameters, responses
2. **Provide examples** - Real-world examples for every schema
3. **Meaningful descriptions** - Markdown-formatted, explain business context
4. **Consistent naming** - kebab-case paths, camelCase properties
5. **Version your API** - Include version in URL or header
6. **Document errors** - Define all error responses with examples
7. **Use operationId** - Unique, descriptive IDs for SDK generation
8. **Validate with linting** - Use Spectral to enforce standards
9. **Keep spec in sync** - Automate validation in CI

## Common Pitfalls

- **Missing required fields** - Forgetting to mark fields as required
- **Inconsistent naming** - Mixing snake_case and camelCase
- **Generic descriptions** - "Returns data" instead of specific details
- **No examples** - Makes spec hard to understand
- **Outdated spec** - Spec doesn't match implementation
- **Overusing anyOf** - Makes schemas hard to understand
- **Missing error responses** - Only documenting happy path
- **No pagination** - List endpoints without pagination info

© curiositech · MIT · curiositech/some_claude_skills

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

Все скиллы по теме «Бэкенд и API» →
openapi-expert personamanagmentlayer Скилл openapi-expert проектирует спецификации OpenAPI 3.0 и 3.1, настраивает полиморфизм схем и генерирует код клиентов или серверов. CX Codex +1 282установок openapi oakoss Настраивает агента на проектирование спецификаций OpenAPI 3.1 и генерацию TypeScript-клиентов. Помогает писать схемы контрактов и документацию для REST API. CX Codex +1 197установок 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установок api-documentation-writer OneWave-AI Скилл api-documentation-writer формирует документацию для REST, GraphQL или gRPC API. Он создаёт спецификации OpenAPI, примеры запросов на нескольких языках и описания ошибок с лимитами. CX Codex +1 389установок 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звёзд репо

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

Весь набор →
windows-95-web-designer Скилл windows-95-web-designer стилизует современные веб-приложения под интерфейс Windows 95 с характерным синим градиентом заголовков, 3D-фасками и кнопкой «Пуск». Переносит ретро-эстетику на чат-ботов и мобильные экраны. CX Codex +1 176установок panic-room-finder Скилл panic-room-finder для Claude Code помогает составить карту дома, заметить возможные пустоты и спланировать безопасную комнату. Описывает неразрушающее обследование собственного жилья. CX Codex +1 176установок pixel-art-infographic-creator Скилл pixel-art-infographic-creator для Claude Code, Cursor и других платформ, который рисует диаграммы и инфографику в стиле 16-битных игр SNES. CX Codex +1 176установок cost-accrual-tracker Скилл cost-accrual-tracker для Claude Code и пяти других платформ, который считает расходы на API в режиме реального времени во время выполнения LLM-запросов. Фиксирует частичные затраты даже при прерванных запросах. CX Codex +1 175установок cost-verification-auditor Скилл cost-verification-auditor для Claude Code сверяет оценку стоимости токенов с фактическими расходами по API. Запускается для поиска причины расхождения прогноза и счёта. CX Codex +1 175установок values-behavioral-interview Скилл values-behavioral-interview для Claude Code помогает готовиться к интервью на соответствие ценностям и разбирать истории о неудачах. В репетициях задаёт подробные уточняющие вопросы. CX Codex +1 174установок interview-loop-strategist Скилл interview-loop-strategist выстраивает план подготовки к собеседованиям на позиции Senior ML/AI в Anthropic и другие компании. Он формирует график занятий, матрицу историй по проектам и координирует этапы. CX Codex +1 173установок interview-simulator Скилл interview-simulator проектирует платформу пробных собеседований с голосом, доской и адаптивной сложностью. Подходит для настройки тренировочных сессий и разбора прогресса. CX Codex +1 169установок

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

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