Что такое Swagger?

Swagger (или Open API) — это спецификация и набор инструментов для проектирования, построения, документирования и использования RESTful веб-сервисов.

Основные компоненты:

• Спецификация OpenAPI (OAS): Языково-независимый формат описания RESTful API в виде JSON или YAML. Описывает доступные эндпоинты, параметры, ответы, схемы данных, авторизацию и метаданные.
• Swagger UI: Инструмент для визуализации и интерактивного взаимодействия с API, описанным в спецификации OpenAPI. Позволяет просматривать документацию и выполнять запросы прямо из браузера.
• Swagger Codegen: Набор инструментов для автоматической генерации серверного кода (скелетов) и клиентских SDK на основе спецификации OpenAPI.

Преимущества использования:

• Единая документация: Создает стандартизированную и всегда актуальную документацию для API.
• Разработка по контракту: Позволяет командам бэкенда и фронтенда работать параллельно, договорившись о контракте API.
• Автоматизация тестирования: Используется для автоматической генерации тестов API (например, с помощью Swagger Inspector).
• Обнаружение API: Упрощает поиск и понимание доступных API в системе.

Пример части спецификации в YAML:

openapi: 3.0.0
info:
  title: Simple API
  version: 1.0.0
paths:
  /items:
    get:
      summary: Get a list of items
      responses:
        '200':
          description: A list of items.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Item'
components:
  schemas:
    Item:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string