Что дают OpenAPI/Swagger и кодогенерация?

Что такое OpenAPI и Swagger?

OpenAPI (ранее Swagger Specification) — это стандарт описания REST API. Спецификация представляет собой файл (JSON или YAML), в котором описываются все эндпоинты, параметры, форматы запросов и ответов. Swagger — это набор инструментов (редактор, UI, кодогенератор), которые работают с этим файлом.

Зачем это нужно?

Основная цель — сделать API понятным и для человека, и для машины. Разработчики могут быстро понять, как работать с API, не читая тонны документации. Автоматическая генерация кода позволяет создавать клиентские библиотеки на разных языках и серверные заглушки, что ускоряет интеграцию.

Пример использования

Допустим, у вас есть API для управления пользователями. Вы описываете его в OpenAPI:

openapi: 3.0.0
info:
  title: User API
  version: 1.0.0
paths:
  /users:
    get:
      summary: Get all users
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string

Из этого файла Swagger UI генерирует интерактивную документацию, где можно прямо в браузере отправлять запросы. А кодогенератор создаёт, например, Python-клиент:

import requests
response = requests.get('https://api.example.com/users')
users = response.json()
for user in users:
    print(user['name'])

Вывод

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