Что такое OpenAPI?

Спецификация OpenAPI (ранее известная как Swagger) — стандартный формат для описания REST API. Она определяет каждый аспект API в машиночитаемом документе: endpoint-ы, HTTP-методы, параметры запросов, форматы ответов, аутентификацию и модели данных.

OpenAPI-спецификация служит контрактом между провайдерами и потребителями API. Как тестировщик, она является вашим источником истины о том, что должен делать API.

OpenAPI vs. Swagger

  • Swagger — оригинальное название, созданное SmartBear
  • OpenAPI — стандартное название после передачи спецификации Linux Foundation
  • Swagger UI и Swagger Editor — инструменты, работающие с OpenAPI-спецификациями
  • Текущая версия: OpenAPI 3.1 (согласована с JSON Schema)

Чтение спецификации OpenAPI

OpenAPI-спецификации пишутся на YAML или JSON. Упрощённый пример:

openapi: 3.1.0
info:
  title: API управления пользователями
  version: 1.0.0
  description: API для управления пользователями

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

paths:
  /users:
    get:
      summary: Список всех пользователей
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 1
        - 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:
      summary: Создать нового пользователя
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateUser'
      responses:
        '201':
          description: Пользователь создан
        '400':
          description: Ошибка валидации

components:
  schemas:
    User:
      type: object
      required: [id, name, email]
      properties:
        id:
          type: integer
        name:
          type: string
          minLength: 1
          maxLength: 100
        email:
          type: string
          format: email
        role:
          type: string
          enum: [admin, user, viewer]
        createdAt:
          type: string
          format: date-time

    CreateUser:
      type: object
      required: [name, email]
      properties:
        name:
          type: string
          minLength: 1
        email:
          type: string
          format: email
        role:
          type: string
          enum: [admin, user, viewer]
          default: user

Ключевые секции

СекцияНазначение
infoНазвание, версия, описание API
serversБазовые URL для разных окружений
pathsEndpoint-ы с методами и параметрами
components/schemasПереиспользуемые модели данных
securityТребования аутентификации

Основы JSON Schema

JSON Schema определяет структуру и правила валидации для JSON-данных. OpenAPI использует JSON Schema для тел запросов и ответов.

Распространённые типы и ограничения 

# Строка с ограничениями
name:
  type: string
  minLength: 1
  maxLength: 255
  pattern: "^[A-Za-z ]+$"

# Число с диапазоном
age:
  type: integer
  minimum: 0
  maximum: 150

# Enum (допустимые значения)
status:
  type: string
  enum: [active, inactive, suspended]

# Массив с типом элемента
tags:
  type: array
  items:
    type: string
  minItems: 1
  maxItems: 10
  uniqueItems: true

# Nullable-поле
deletedAt:
  type: ["string", "null"]
  format: date-time

Тест-кейсы из схемы

Каждое ограничение схемы генерирует тест-кейсы:

Правило схемыПозитивный тестНегативный тест
required: [name]Включить поле nameПропустить поле name
minLength: 1Отправить "A"Отправить "" (пусто)
maxLength: 100Отправить 100 символовОтправить 101 символ
minimum: 0Отправить 0Отправить -1
enum: [a, b, c]Отправить "a"Отправить "d"
type: integerОтправить 42Отправить "сорок два"
format: emailОтправить a@b.comОтправить не-email

Валидация схем на практике

Валидация в Postman

Используйте встроенную валидацию JSON Schema в Postman:

// Во вкладке Tests
const schema = {
  type: "object",
  required: ["id", "name", "email"],
  properties: {
    id: { type: "number" },
    name: { type: "string" },
    email: { type: "string", format: "email" },
    role: { type: "string", enum: ["admin", "user", "viewer"] }
  },
  additionalProperties: false
};

pm.test("Ответ соответствует схеме", function () {
  const response = pm.response.json();
  const valid = tv4.validate(response, schema);
  pm.expect(valid).to.be.true;
});

Валидация на Python (jsonschema) 

import jsonschema
import requests

schema = {
    "type": "object",
    "required": ["id", "name", "email"],
    "properties": {
        "id": {"type": "integer"},
        "name": {"type": "string", "minLength": 1},
        "email": {"type": "string", "format": "email"}
    }
}

response = requests.get("https://api.example.com/users/1")
data = response.json()

try:
    jsonschema.validate(instance=data, schema=schema)
    print("Валидация схемы успешна")
except jsonschema.ValidationError as e:
    print(f"Валидация схемы не пройдена: {e.message}")

Автоматизированное тестирование схем с Schemathesis

Schemathesis автоматически генерирует тест-кейсы из вашей OpenAPI-спецификации:

pip install schemathesis

# Запуск против работающего API
schemathesis run https://api.example.com/openapi.json

# С конкретными проверками
schemathesis run https://api.example.com/openapi.json \
  --checks all \
  --stateful=links

Автоматически тестирует граничные значения, невалидные типы, отсутствующие поля и многое другое — всё извлечённое из спецификации.

Стратегия тестирования на основе спецификаций

Тестирование спецификации vs. реализации

  1. Соответствует ли реализация спецификации? — Валидируйте, что реальные ответы соответствуют задокументированным схемам
  2. Спецификация полна? — Ищите недокументированные endpoint-ы, поля или коды ошибок
  3. Ограничения применяются? — Проверяйте, что валидации minLength, maxLength, enum, format реально работают
  4. Граничные случаи обрабатываются? — Тестируйте nullable-поля, опциональные поля, дополнительные свойства

Типичные баги схем

БагКак найти
Отсутствующие обязательные поля в ответеВалидация по схеме
Неправильные типы данных в ответеВалидация схемы ловит string vs integer
Недокументированные поля в ответеИспользовать additionalProperties: false
Enum-значения не применяютсяОтправлять невалидные enum-значения в запросах
Формат не валидируетсяОтправлять некорректные email, дату, URI

Практическое упражнение

  1. Прочитайте спецификацию: Изучите спецификацию API Petstore в Swagger UI. Определите все endpoint-ы, схемы и обязательные поля.
  2. Напишите JSON Schema для объекта продукта: id (integer), name (string, 1-200 символов), price (number, min 0), category (enum), inStock (boolean).
  3. Валидируйте ответы: Используйте Postman для отправки запросов к JSONPlaceholder и напишите тесты валидации схем для endpoint-ов /posts и /users.
  4. Найдите нарушения спецификации: Намеренно отправьте невалидные данные и проверьте, что API возвращает корректные ошибки валидации согласно спецификации.

Ключевые выводы

  • Спецификации OpenAPI определяют полный контракт API — endpoint-ы, параметры, схемы запросов/ответов и аутентификацию
  • JSON Schema предоставляет правила валидации (типы, диапазоны, паттерны, обязательные поля), которые напрямую преобразуются в тест-кейсы
  • Каждое ограничение схемы генерирует как позитивные, так и негативные тестовые сценарии
  • Автоматизированные инструменты вроде Schemathesis могут генерировать комплексные тесты напрямую из OpenAPI-спецификаций
  • Валидация схем автоматически ловит несоответствия типов данных, отсутствующие поля и нарушения контракта