📘 Swagger (OpenAPI)

Структура спецификации OpenAPI 3: пути, параметры, схемы, ответы, безопасность.

Шпаргалки · Аналитика · #openapi #swagger #api #documentation

Что это

OpenAPI это стандарт описания REST API в YAML или JSON. Swagger название набора инструментов: Swagger UI (документация в браузере), Swagger Editor, Swagger Codegen. По спецификации генерируют документацию, клиентов, серверные заглушки и тесты.

Каркас

openapi: 3.0.3
info:
  title: Shop API
  version: 1.0.0
servers:
  - url: https://api.example.com/v1
tags:
  - name: users
paths:
  /users:
    get:
      tags: [users]
      summary: Список пользователей
      parameters:
        - name: limit
          in: query
          schema: { type: integer, default: 20, maximum: 100 }
      responses:
        '200':
          description: Успешно
          content:
            application/json:
              schema:
                type: array
                items: { $ref: '#/components/schemas/User' }
    post:
      tags: [users]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/NewUser' }
      responses:
        '201': { description: Создан }
        '422': { $ref: '#/components/responses/ValidationError' }
  /users/{id}:
    get:
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: integer }
      responses:
        '200':
          description: Пользователь
          content:
            application/json:
              schema: { $ref: '#/components/schemas/User' }
        '404': { description: Не найден }
components:
  schemas:
    User:
      type: object
      required: [id, email]
      properties:
        id:    { type: integer, example: 42 }
        email: { type: string, format: email }
        role:  { type: string, enum: [admin, user] }
    NewUser:
      type: object
      required: [email]
      properties:
        email: { type: string, format: email }
  responses:
    ValidationError:
      description: Ошибка валидации
  securitySchemes:
    bearerAuth: { type: http, scheme: bearer, bearerFormat: JWT }
security:
  - bearerAuth: []

Типы данных

string (форматы date, date-time, email, uuid, uri), integer (int32, int64), number, boolean, array, object. Ограничения: minLength, maxLength, pattern, minimum, maximum, enum, nullable.

Где применяется параметр (in)

path, query, header, cookie. Тело описывается в requestBody.

Композиция схем

allOf (все), oneOf (одна из), anyOf (любая), $ref (ссылка на компонент).

Инструменты

Подход

• Design first: сначала спецификация, потом код.
• Code first: спецификация генерируется из кода (springdoc, FastAPI, NestJS Swagger).

Совет: Давайте example у полей и описания у кодов ошибок: по ним пишут тесты и интеграции.