OpenAPI / Swagger

openapi: 3.0.0                      # версия спецификации
info:                               # метаинформация
  title: User API
  description: API для управления пользователями
  version: 1.0.0
  contact:
    name: API Support
    email: support@example.com
  license:
    name: MIT

servers:                            # где живёт API
  - url: https://api.example.com/v1
    description: Production server
  - url: https://staging-api.example.com/v1
    description: Staging server

paths:                              # эндпоинты
  /users:
    get:
      summary: Получить список пользователей
      parameters: [...]
      responses: {...}
    post:
      summary: Создать пользователя
      requestBody: {...}
      responses: {...}
  /users/{id}:
    get:
      summary: Получить пользователя по ID
      parameters: [...]
      responses: {...}

components:                         # переиспользуемые части
  schemas: {...}                    # модели данных
  parameters: {...}                 # параметры
  responses: {...}                  # ответы
  securitySchemes: {...}            # схемы аутентификации

security:                           # глобальная аутентификация
  - bearerAuth: []

tags:                               # группировка эндпоинтов
  - name: Users
    description: Операции с пользователями

info:
  title: User API
  description: |
    API для управления пользователями.
    
    **Возможности:**
    * Создание пользователя
    * Получение информации
    * Обновление профиля
    * Удаление пользователя
  version: 1.0.0
  termsOfService: https://example.com/terms
  contact:
    name: API Team
    url: https://example.com/support
    email: api@example.com
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT

servers:
  - url: https://api.example.com/v1
    description: Production
  - url: https://staging-api.example.com/v1
    description: Staging
  - url: https://dev-api.example.com/v1
    description: Development
  - url: http://localhost:8080/v1
    description: Local development

paths:
  /users:
    get:
      summary: Получить список пользователей
      description: Возвращает список пользователей с пагинацией
      operationId: listUsers
      tags:
        - Users

parameters:
  - name: id
    in: path
    required: true
    description: Идентификатор пользователя
    schema:
      type: integer
      example: 123
  - name: status
    in: query
    required: false
    description: Фильтр по статусу
    schema:
      type: string
      enum: [active, pending, blocked]
      default: active
  - name: X-Request-ID
    in: header
    required: false
    description: Идентификатор запроса для трассировки
    schema:
      type: string

requestBody:
  required: true
  description: Данные нового пользователя
  content:
    application/json:
      schema:
        $ref: '#/components/schemas/UserCreate'
      examples:
        minimal:
          summary: Минимальный пользователь
          value:
            name: Иван
            email: ivan@example.com
        full:
          summary: Полные данные
          value:
            name: Иван Петров
            email: ivan@example.com
            age: 30
            phone: +7-999-123-45-67

responses:
  '200':
    description: Успешный ответ
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/User'
  '201':
    description: Пользователь создан
    headers:
      Location:
        description: URL созданного ресурса
        schema:
          type: string
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/User'
  '400':
    description: Неверный запрос
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/Error'
  '401':
    description: Не авторизован
  '403':
    description: Нет прав
  '404':
    description: Пользователь не найден
  '422':
    description: Ошибка валидации
  '429':
    description: Слишком много запросов
  '500':
    description: Внутренняя ошибка сервера

components:
  schemas:
    User:
      type: object
      required:
        - id
        - name
        - email
      properties:
        id:
          type: integer
          example: 123
          description: Уникальный идентификатор
        name:
          type: string
          minLength: 1
          maxLength: 100
          example: Иван Петров
        email:
          type: string
          format: email
          example: ivan@example.com
        age:
          type: integer
          minimum: 0
          maximum: 150
          nullable: true
        created_at:
          type: string
          format: date-time
          example: 2024-01-15T10:30:00Z
    
    Error:
      type: object
      properties:
        code:
          type: string
          example: VALIDATION_ERROR
        message:
          type: string
          example: Invalid input data
        details:
          type: object
          additionalProperties:
            type: array
            items:
              type: string

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT токен, полученный при аутентификации
    
    apiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: API ключ для доступа к публичным эндпоинтам
    
    basicAuth:
      type: http
      scheme: basic
      description: Basic аутентификация
    
    oauth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://auth.example.com/oauth/authorize
          tokenUrl: https://auth.example.com/oauth/token
          scopes:
            read:users: Чтение пользователей
            write:users: Запись пользователей

# Глобальное применение
security:
  - bearerAuth: []
  - apiKeyAuth: []

# Переопределение на уровне эндпоинта
paths:
  /health:
    get:
      security: []   # без аутентификации

paths:
  /users:
    get:
      summary: Список пользователей
      parameters:
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/offset'
        - name: status
          in: query
          schema:
            $ref: '#/components/schemas/UserStatus'
    post:
      summary: Создание пользователя
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserCreate'

# Хорошо
paths:
  /users:           # ресурс во множественном числе
  /users/{id}:      # параметр в фигурных скобках
  /users/{id}/orders  # вложенный ресурс

# Плохо
paths:
  /getUsers:        # глагол в URL
  /user/{userId}:   # непоследовательное именование

# Вариант 1: в URL
servers:
  - url: https://api.example.com/v1

# Вариант 2: в заголовке (не рекомендуется)
# Вариант 3: отдельная спецификация на версию

# Плохо
description: Get user

# Хорошо
description: |
  Возвращает информацию о пользователе по его идентификатору.
  
  **Требуется аутентификация:** Да
  **Права:** Пользователь может видеть только свой профиль, администратор — любые

# Плохо (нет примеров)
schema:
  type: object
  properties:
    name:
      type: string

# Хорошо
schema:
  type: object
  properties:
    name:
      type: string
      example: Иван Петров
      description: Полное имя пользователя

responses:
  '400':
    description: Неверный запрос
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/Error'
        examples:
          invalid_email:
            summary: Неверный формат email
            value:
              code: INVALID_EMAIL
              message: Email должен быть в формате user@example.com
          missing_name:
            summary: Отсутствует имя
            value:
              code: MISSING_FIELD
              message: Поле 'name' обязательно

get:
  deprecated: true
  description: Устаревший метод. Используйте `/api/v2/users`