OpenAPI и Swagger для документирования API

Swagger стоит изучить в любом случае. Как разработчик приложений, ты обязательно столкнёшься с API. Swagger станет твоим лучшим помощником, если научишься с ним работать. Это не сложно, разве что может потребоваться API Key, но даже это решаемо. Swagger, как и Postman, предоставляет готовый интерфейс для тестирования. Ты выбираешь нужный endpoint и сразу можешь отправить тестовый запрос.

OpenAPI является стандартом для машиночитаемого описания REST API и основой для интерактивной документации, mock-серверов и генерации кода.

Краткое описание

OpenAPI это формат спецификации для REST API, который описывает endpoints, методы, параметры, схемы запросов и ответов, коды статуса, форматы ошибок и механизмы безопасности. Обычно пишется на YAML или JSON и служит единственным источником истины для разработчиков, тестировщиков, генераторов клиентов и документации. Swagger это исторический термин, который сегодня обозначает набор инструментов вокруг OpenAPI, таких как Swagger UI, Swagger Editor и Swagger Codegen. OpenAPI позволяет применять подход API First Design, создавать автоматизированные тесты и генерировать интерактивную документацию API. Хорошая OpenAPI спецификация полна, консистентна и содержит примеры, благодаря чему пользователи могут понять и протестировать API без изучения исходного кода.

Важные компоненты

Версия OpenAPI

OpenAPI поддерживает версии 2.0, 3.0 и 3.1. Версии 3.0 и 3.1 обладают большей гибкостью, чем 2.0, в том числе при определении запросов и ответов, ссылок и callbacks. Для новых проектов используй актуальную версию, старые поддерживай только из соображений совместимости.

Info и метаданные

Блок info содержит основные сведения: название, версию, описание и контактную информацию. Эти метаданные важны для идентификации API и автоматической генерации документации.

Server URLs

Server URLs определяют, по каким адресам доступен API. Ты можешь указать несколько окружений: development, staging и production. Переменные позволяют делать части URL динамическими.

Paths и операции

Paths описывают endpoints API. Каждый path может содержать несколько операций: get, post, put, delete, patch. Каждая операция включает summary, description, tags, параметры, request body и responses.

Components и schemas

Components содержат переиспользуемые определения: schemas, parameters, responses, headers и security schemas. Schemas определяют структуру данных запросов и ответов с типами, обязательными полями, форматами и примерами.

Parameters

Параметры передаются в path, query, header или cookie. Они определяются с указанием имени, типа, формата, обязательности и описания. Примеры и правила валидации, такие как minLength или pattern, повышают качество.

Request Body

Request Body описывает данные, которые клиент должен отправить при POST, PUT или PATCH. Обычно ссылается на schema и может поддерживать несколько типов контента: application/json, application/xml.

Responses

Responses определяют возможные ответы операции. Каждый код статуса описывается через description, content-type и schema. Также важно полностью документировать ошибочные ответы, такие как 400 или 404.

Security Schemas

Security Schemas описывают, как защищён API. Типичные способы это HTTP Basic, Bearer Token, OAuth2 и API Keys. Schemas определяются в Components и ссылаются в операциях.

Swagger UI и Redoc

Swagger UI и Redoc это инструменты, которые генерируют интерактивную HTML документацию из OpenAPI спецификации. Swagger UI позволяет тестировать endpoints прямо в браузере, Redoc акцентирует внимание на красивом представлении и удобочитаемости.

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

OpenAPI Generator создаёт клиентский и серверный код из спецификации. Это ускоряет разработку, снижает количество ошибок и гарантирует, что клиент и сервер работают по одному контракту. Поддерживаются многие языки программирования и фреймворки.

Практический пример

Shop определяет свой Order API с использованием OpenAPI:

openapi: 3.0.3
info:
  title: Shop API
  version: 1.0.0
  description: API для управления заказами

servers:
  - url: https://api.shop.example.com/v1

paths:
  /orders:
    post:
      summary: Создание заказа
      tags:
        - Orders
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrderRequest'
      responses:
        '201':
          description: Заказ создан
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
        '400':
          description: Некорректный ввод

components:
  schemas:
    OrderRequest:
      type: object
      required:
        - customerId
        - items
      properties:
        customerId:
          type: integer
          example: 123
        items:
          type: array
          items:
            $ref: '#/components/schemas/OrderItem'
    OrderItem:
      type: object
      required:
        - productId
        - quantity
      properties:
        productId:
          type: integer
          example: 42
        quantity:
          type: integer
          minimum: 1
          example: 2
    Order:
      type: object
      properties:
        orderId:
          type: integer
          example: 98765
        status:
          type: string
          example: created

Из этой спецификации Swagger UI может генерировать интерактивную документацию, OpenAPI Generator может создать клиентов для JavaScript, Python или Java, а тестировщики могут выполнять валидацию по схеме.

FAQ: OpenAPI и Swagger

1. Что такое OpenAPI?

OpenAPI это машиночитаемый формат для описания REST API. Он определяет endpoints, методы, параметры, schemas, коды статуса и механизмы безопасности.

2. В чём разница между OpenAPI и Swagger?

OpenAPI это спецификация. Swagger это торговая марка для инструментов, таких как Swagger UI, Swagger Editor и Swagger Codegen, которые используют документы OpenAPI. Раньше саму спецификацию называли Swagger.

3. В каком формате пишется OpenAPI?

OpenAPI пишется на YAML или JSON. YAML распространён больше благодаря лучшей читаемости, JSON часто используется для автоматизированной обработки.

4. Что такое Swagger UI?

Swagger UI это инструмент, который генерирует интерактивную HTML документацию из OpenAPI спецификации. Пользователи могут тестировать endpoints прямо в браузере.

5. Что такое Redoc?

Redoc это инструмент с открытым исходным кодом, который генерирует красивую и удобочитаемую документацию из OpenAPI спецификаций. Хорошо подходит для документации конечных пользователей.

6. Что такое Components в OpenAPI?

Components содержат переиспользуемые определения: schemas, параметры, responses и security schemas. Они обеспечивают консистентную и легко поддерживаемую спецификацию.

7. Что такое генерация кода с OpenAPI?

Генерация кода создаёт клиентский или серверный код из OpenAPI спецификации. Это ускоряет разработку, снижает ошибки и гарантирует, что клиент и сервер работают по одному контракту.

8. Что такое schema в OpenAPI?

Schema в OpenAPI определяет структуру данных. Она задаёт типы, обязательные поля, форматы, примеры и правила валидации для request bodies и responses.

9. Что такое Security Schemas?

Security Schemas описывают, как защищён API. Типичные способы это Bearer Token, API Keys, HTTP Basic и OAuth2. Они определяются в Components и ссылаются в операциях.

10. Что такое Single Source of Truth?

Single Source of Truth это единый авторитетный источник информации. OpenAPI является Single Source of Truth для API, из которой генерируется документация, тесты и код.

11. Что такое API First Design?

API First Design означает, что спецификация API создаётся ДО реализации. OpenAPI это центральный инструмент для такого подхода.

12. Что такое mock-server из OpenAPI?

Mock-server имитирует API на основе OpenAPI спецификации. Он возвращает предопределённые ответы и позволяет разрабатывать клиентов, пока реальный API ещё не готов.

13. Какова полезность OpenAPI для тестировщиков?

Тестировщики могут использовать OpenAPI для создания валидации по схеме, contract tests и автоматизированных тестов. Спецификация служит справочником для ожидаемых requests и responses.

14. Что такое OpenAPI Linting?

OpenAPI Linting проверяет спецификацию на нарушения правил, несогласованности и недостающие элементы. Инструменты вроде Spectral помогают обеспечивать качество спецификаций.

15. Какие best practices для OpenAPI спецификаций?

Best practices включают полное описание endpoints и responses, переиспользуемые Components, содержательные примеры, ясные описания, корректные security schemas, версионирование и регулярное обновление спецификации.

Продолжаем путь изучения API

Следующая статья в этом цикле посвящена лучшим практикам документирования API — как писать документацию, которую разработчики реально поймут и будут использовать.

Täglicher Artikel