← Блог Главная
Главная › Блог › OpenAPI спецификация
Документация

OpenAPI спецификация: Создание и использование

📅 7 сентября 2025 ⏱ 12 минут чтения ✍️ LightBox API Team
← Вернуться к статьям

Введение

OpenAPI спецификация (ранее известная как Swagger) — это стандарт описания RESTful API в машиночитаемом формате. Это язык, на котором Frontend и Backend команды договариваются о контракте взаимодействия.

В современной разработке OpenAPI стала де-факто стандартом для документирования, проектирования и тестирования API. Спецификация позволяет автоматически генерировать документацию, клиентские SDK, Mock-серверы и тесты.

🎯 В этом руководстве: Вы научитесь создавать OpenAPI спецификации с нуля, поймёте структуру документа, изучите best practices и узнаете, как использовать спецификацию для ускорения разработки.

Что такое OpenAPI? 📄

OpenAPI Specification (OAS) — это формат описания API, который позволяет описать:

История: от Swagger к OpenAPI

2011

Рождение Swagger

Tony Tam создаёт Swagger для документирования API в Wordnik

2015

Swagger 2.0

Становится популярным стандартом в индустрии

2016

Переименование в OpenAPI

Swagger передан в Linux Foundation, становится OpenAPI Initiative

2017

OpenAPI 3.0

Выпуск новой версии с улучшениями и новыми возможностями

2021

OpenAPI 3.1

Полная совместимость с JSON Schema, новые фичи

Зачем нужна OpenAPI спецификация? 🤔

📖 Автоматическая документация

Генерация интерактивной документации с помощью Swagger UI, Redoc. Документация всегда актуальна и синхронизирована с кодом.

🔄 Contract-First разработка

Frontend и Backend работают параллельно по единому контракту. Снижается количество недопониманий и переделок.

🎭 Mock серверы

Автоматическое создание Mock API из спецификации. Frontend начинает работать до готовности Backend.

🤖 Генерация кода

Автогенерация клиентских SDK, серверных заглушек, моделей данных для различных языков программирования.

✅ Валидация

Автоматическая проверка соответствия запросов и ответов спецификации. Раннее обнаружение несоответствий.

🧪 Автоматизация тестирования

Генерация тестов на основе спецификации. Contract testing, интеграционное тестирование.

Структура OpenAPI 3.0 📐

OpenAPI спецификация пишется в форматах YAML или JSON. YAML предпочтительнее, так как более читаем для человека.

Поле Описание Обязательность
openapi Версия спецификации OpenAPI (например, "3.0.0") Required
info Метаданные API (название, версия, описание, контакты) Required
servers Список серверов API (URL окружений: dev, staging, prod) Optional
paths Endpoints и операции API (основное содержание) Required
components Переиспользуемые компоненты (schemas, parameters, responses) Optional
security Глобальные настройки безопасности Optional
tags Теги для группировки операций Optional
externalDocs Ссылка на внешнюю документацию Optional

Создание спецификации с нуля 🛠

Шаг 1: Базовая структура

Начнём с минимальной структуры OpenAPI документа:

YAML 
openapi: 3.0.3
info:
  title: My API
  description: API для управления пользователями
  version: 1.0.0
  contact:
    name: API Support
    email: support@example.com

servers:
  - url: https://api.example.com/v1
    description: Production сервер
  - url: https://staging-api.example.com/v1
    description: Staging сервер

paths: {}
components: {}

Шаг 2: Определение Endpoints

Добавим endpoint для получения списка пользователей:

YAML 
paths:
  /users:
    get:
      summary: Получить список пользователей
      description: Возвращает список всех пользователей с пагинацией
      tags:
        - Users
      parameters:
        - name: page
          in: query
          description: Номер страницы
          required: false
          schema:
            type: integer
            default: 1
            minimum: 1
        - name: limit
          in: query
          description: Количество элементов на странице
          required: false
          schema:
            type: integer
            default: 10
            minimum: 1
            maximum: 100
      responses:
        '200':
          description: Успешный ответ
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/User'
                  meta:
                    type: object
                    properties:
                      total:
                        type: integer
                      page:
                        type: integer
                      limit:
                        type: integer
        '400':
          description: Неверные параметры запроса

Шаг 3: Определение Schemas

Создадим переиспользуемую схему для модели User:

YAML 
components:
  schemas:
    User:
      type: object
      required:
        - id
        - email
        - name
      properties:
        id:
          type: integer
          format: int64
          example: 1
        email:
          type: string
          format: email
          example: user@example.com
        name:
          type: string
          example: Иван Иванов
        age:
          type: integer
          minimum: 0
          maximum: 150
          example: 30
        role:
          type: string
          enum:
            - admin
            - user
            - guest
          default: user
        created_at:
          type: string
          format: date-time
          example: '2025-10-07T10:30:00Z'

Шаг 4: POST запрос для создания пользователя

YAML 
paths:
  /users:
    post:
      summary: Создать нового пользователя
      description: Создаёт нового пользователя в системе
      tags:
        - Users
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - email
                - name
              properties:
                email:
                  type: string
                  format: email
                  example: newuser@example.com
                name:
                  type: string
                  minLength: 2
                  maxLength: 100
                  example: Новый Пользователь
                age:
                  type: integer
                  minimum: 18
                  maximum: 100
      responses:
        '201':
          description: Пользователь создан
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '400':
          description: Неверные данные
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: Email уже используется

Шаг 5: Добавление аутентификации

YAML 
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
    apiKey:
      type: apiKey
      in: header
      name: X-API-Key

security:
  - bearerAuth: []

paths:
  /users:
    get:
      security:
        - bearerAuth: []
      # ... остальная конфигурация

Полный пример спецификации 📝

YAML 
openapi: 3.0.3
info:
  title: Users API
  description: API для управления пользователями
  version: 1.0.0
  contact:
    name: API Support
    email: support@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

tags:
  - name: Users
    description: Операции с пользователями

paths:
  /users:
    get:
      summary: Получить список пользователей
      tags:
        - Users
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/LimitParam'
      responses:
        '200':
          description: Успешный ответ
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserListResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedError'

    post:
      summary: Создать пользователя
      tags:
        - Users
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateUserRequest'
      responses:
        '201':
          description: Пользователь создан
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '400':
          $ref: '#/components/responses/BadRequestError'

  /users/{id}:
    get:
      summary: Получить пользователя по ID
      tags:
        - Users
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Успешный ответ
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '404':
          $ref: '#/components/responses/NotFoundError'

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

  parameters:
    PageParam:
      name: page
      in: query
      description: Номер страницы
      required: false
      schema:
        type: integer
        default: 1
        minimum: 1

    LimitParam:
      name: limit
      in: query
      description: Количество элементов на странице
      required: false
      schema:
        type: integer
        default: 10
        minimum: 1
        maximum: 100

  schemas:
    User:
      type: object
      required:
        - id
        - email
        - name
      properties:
        id:
          type: integer
          example: 1
        email:
          type: string
          format: email
          example: user@example.com
        name:
          type: string
          example: Иван Иванов
        created_at:
          type: string
          format: date-time

    CreateUserRequest:
      type: object
      required:
        - email
        - name
      properties:
        email:
          type: string
          format: email
        name:
          type: string
          minLength: 2
          maxLength: 100

    UserListResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/User'
        meta:
          type: object
          properties:
            total:
              type: integer
            page:
              type: integer
            limit:
              type: integer

    Error:
      type: object
      properties:
        error:
          type: string
        message:
          type: string

  responses:
    UnauthorizedError:
      description: Не авторизован
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'

    BadRequestError:
      description: Неверный запрос
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'

    NotFoundError:
      description: Не найдено
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'

security:
  - bearerAuth: []

Инструменты для работы с OpenAPI 🛠

✏️
Swagger Editor
Онлайн редактор с валидацией и предпросмотром
📖
Swagger UI
Интерактивная документация из спецификации
📚
Redoc
Красивая документация с responsive дизайном
🤖
OpenAPI Generator
Генерация SDK, серверов, моделей
📦
LightBox API
Mock API сервер из OpenAPI спецификации
✅
Spectral
Линтер для проверки качества спецификации
🔄
Prism
Mock сервер с валидацией запросов
🎨
Stoplight Studio
Визуальный редактор API
📮
Postman
Импорт OpenAPI для тестирования

Best Practices 🌟

  1. Используйте $ref для переиспользования
    Выносите повторяющиеся schemas, parameters, responses в components. Это делает спецификацию чище и проще в поддержке.
  2. Добавляйте примеры (examples)
    Примеры помогают разработчикам понять ожидаемые форматы данных и ускоряют интеграцию.
  3. Описывайте все коды ответов
    Не ограничивайтесь 200 OK — опишите 400, 401, 404, 500 и другие возможные ответы.
  4. Используйте теги для группировки
    Группируйте endpoints по функциональности (Users, Products, Orders) для удобной навигации.
  5. Определяйте форматы данных
    Используйте format для строк (email, uri, date-time) и constraints (minLength, maximum).
  6. Версионируйте API
    Включайте версию в URL (/v1/, /v2/) или используйте заголовки для версионирования.
  7. Валидируйте спецификацию
    Используйте линтеры (Spectral) для проверки на соответствие best practices.
  8. Документируйте аутентификацию
    Чётко опишите требования к безопасности и способы авторизации.
  9. Используйте enum для ограниченных значений
    Если поле может принимать только определённые значения (статусы, роли), используйте enum.
  10. Храните спецификацию в Git
    Версионируйте спецификацию вместе с кодом для отслеживания изменений.

Использование с LightBox API 🚀

LightBox API позволяет мгновенно создать Mock API из вашей OpenAPI спецификации:

Как это работает:

  1. Загрузите вашу OpenAPI спецификацию (YAML или JSON) в LightBox API
  2. Система автоматически создаст все endpoints с примерами ответов
  3. Получите облачный URL для использования в разработке и тестировании
  4. Настройте динамические ответы, задержки, коды ошибок
  5. Frontend команда начинает работу без ожидания Backend

Преимущества интеграции:

Распространённые ошибки ⚠️

Заключение

OpenAPI спецификация — это не просто документация, а мощный инструмент для:

Начните создавать OpenAPI спецификации для ваших проектов, используйте Mock API для ускорения разработки, и вы увидите, как повысится продуктивность всей команды.

Создайте Mock API из OpenAPI спецификации

Импортируйте вашу спецификацию в LightBox API и получите рабочий Mock сервер за 2 минуты. Бесплатный старт.

Попробовать бесплатно →
← Вернуться к статьям
Предложения Контакты Помощь Правовая информация
© 2024