SavePearlHarbor

OpenAPI/Swagger для начинающих

—

от автора

admin

Для кого эта статья

В основном для аналитиков, которые впервые сталкиваются с необходимостью описания запросов в Swagger, но может быть полезна всем, кто хочет разобраться или ищет подсказку как описывать запросы в этом формате.

Плюсы

Если вы в первый раз решили использовать OpenAPI/Swagger, то может показаться, что это слишком сложно в плане синтаксиса, но плюсы перевешивают. Давайте их обозначим:

  1. Для большого количества методов с повторяющимися элементами OpenAPI позволяет в итоге ускорить описание

  2. OpenAPI дает более широкие возможности описания запросов и их элементов, чем любая таблица в Confluence.

  3. Swagger можно использовать при тестировании.

  4. Из готового документа можно сгенерировать сервер и клиент.

Я часто встречал мнение, что OpenAPI/Swagger подходит только для генерации из кода, и что синтаксис для написания руками перегружен для большинства джунов-аналитиков. Но, на мой взгляд, это не так: этот формат, древовидный и хорошо задокументированный,  изучать чуть сложнее, чем json.

Концепция

Документ YAML OpenAPI представляет собой дерево с набором ветвей. Есть несколько базовых ветвей, таких как запросы или компоненты. Они в свою очередь также могут содержать дополнительные ветви, содержащие описание операций, параметры запросов и схемы ответов. 

Важно, что можно ссылаться на существующие объекты с помощью указания путей до них через $ref, например: «#/components/schemas/AllOfExampleGet». И это одно из ключевых преимуществ: какие-то элементы могут использоваться повторно.

Пройтись по дереву можно здесь

Пройтись по дереву можно здесь

Чтобы начать описывать запросы, достаточно освоить два основных раздела: запросы и компоненты.

Компоненты

Начнем с компонентов, основных кирпичиков, позволяющий вынести за пределы конкретных запросов однотипные описания. Вынос описания в отдельные компоненты дает ряд преимуществ:

  • уменьшает копипаст и длину кода;

  • позволяет одновременно редактировать сразу несколько запросов через их общий компонент.

В компоненты можно вынести:

  • schemas: определяет структур данных (JSON Schema), которые могут использоваться в теле запросов и ответов;

  • responses: определяет возможные ответы;

  • parameters: определяет параметры запросов;

  • examples: примеры данных;

  • requestBodies: определяет тело запросов;

  • headers: определяют заголовки;

  • securitySchemes: определяет схему безопасности, такие как API ключи, токены и др.;

  • links: определяет связь между запросами для перехода между ресурсами;

  • callbacks: определяет обратные вызовы, которые описывают, как ваш API будет уведомлять клиента.

Чаще всего используются schemas и responses. Schemas позволяет описать повторяющиеся ответы и тела запросов, а responses − вынести описание ошибок (200 ответы тоже можно вынести, но чаще всего они отличаются от запроса к запросу). Headers, securitySchemes, parameters − вторые по частоте использования в документации, которую я видел.

Schemas

Schemas позволяет управлять шаблонными структурами данных. Схема содержит в себе отдельные классы, которые содержат в себе описание входящих в них элементов. Например:

Category:   type: object   properties:     id:       type: integer       format: int64       example: 1     name:       type: string       example: Dogs   xml:     name: category

Это класс Category с типом объекта, у которого есть свойства: id, name. Для последних также указан тип, формат и пример значения.

Type указывает на то, какие еще параметры ожидаются для этого элемента. Type может принимать следующие значения:

Type может принимать следующие значения:

  • «string» (строка): для текстовых данных;

  • «number» (число): для числовых данных, включая как целые числа, так и числа с плавающей точкой;

  • «integer» (целое число): для целочисленных данных;

  • «boolean» (булев тип): для логических значений true или false;

  • «object» (объект): для структурированных данных, например, объектов JSON;

  • «array» (массив): для упорядоченного списка элементов;

  • «null» (пусто): для отсутствующего значения.

В случае, если это не object или array, данный элемент будет обычным параметром со значением. Заполнение класса такого типа не будет отличаться от заполнения любого другого параметра. Поэтому важнее рассмотреть object и array, которые используются чаще всего.

Object и array позволяют задавать сложные структуры, как это было показано выше для Category. При создании массива нужно дополнительно указать элемент разметки – items. Например, так:

 type: array   items:     type: object     properties:       name:         type: string       age:         type: integer       email:         type: string         format: email

Список элементов

Значения, которые можно установить для каждого из используемых элементов:

Значения элементов:

  1. title: имя свойства;

  2. description: рредоставляет подробное описание свойства;

  3. default: задает значение по умолчанию для свойства, если оно не предоставлено;

  4. maximum и minimum: указывает максимальное и минимальное значение числового свойства;

  5. exclusiveMaximum и exclusiveMinimum: указывает, являются ли максимальное и минимальное значения исключительными или включительными;

  6. maxLength и minLength: указывает максимальную и минимальную длину строкового свойства;

  7. pattern: применяет валидацию строки на основе регулярного выражения;

  8. format: указывает формат данных. Общие форматы включают «email», «date», «uri» и т. д.

    1. string (строка):

      1. format: date-time — строка с датой и временем в формате RFC 3339.

      2. format: date — строка с датой в формате YYYY-MM-DD.

      3. format: password — строка, предназначенная для пароля.

    2. number (число):

      1. format: float — десятичное число с плавающей точкой (32 бита).

      2. format: double — десятичное число с плавающей точкой (64 бита).

      3. format: int32 — 32-битное целое число.

      4. format: int64 — 64-битное целое число.

    3. integer (целое число):

      1. format: int32 — 32-битное целое число.

      2. format: int64 — 64-битное целое число.

    4. boolean (булев тип):

    5. array (массив):

    6. items — определение типа элементов массива.

    7. object (объект):

    8. properties — определение свойств объекта.

    9. null (пусто):

  9. nullable: позволяет свойству принимать значение null.

  10. readOnly и writeOnly: указывает, является ли свойство доступным только для чтения или только для записи.

  11. example: предоставляет примерное значение для свойства.

  12. enum: указывает список допустимых значений для свойства.

  13. items: описывает свойства элементов в массиве.

  14. uniqueItems: указывает, должны ли элементы в массиве быть уникальными.

$ref: предоставляет ссылку на внешнее определение.

Этот список я рекомендую запомнить лучше всего, так как он позволяет наиболее точно описать требования к элементам класса.

Запросы

В запросе можно указать следующий набор свойств:

  • summary: краткое описание операции;

  • description: подробное описание операции;

  • tags: список тегов, к которым относится операция;

  • parameters: список параметров, необходимых для выполнения операции;

  • responses: список возможных ответов от сервера;

  • requestBody: описание тела запроса.

С summary все просто, оно отображается рядом с названием метода в свернутом виде. С description все чуть сложнее, в него можно засунуть не просто текстовое описание, markdown. Например, такой:

description: >-      Метод отвечает за получение данных о пользователе        * Если пользователь не найден, нужно вернуть ошибку        * Если пользователь удален, нужно вернуть ошибку

Поэтому можно описывать какие-то важные вещи прямо в описании запроса.

Tags позволяют разметить, в какой блок должен быть помещен запрос. Например, вы делаете запросы про информацию о магазине. Укажите у них одинаковый тег, и они будут сгруппированы в одном блоке. Опционально описание тегов можно задать в отдельном разделе описания всей документации.

parameters имеет следующую структуру:

/users/{userId}:   get:     parameters:       - name: userId         in: path         required: true         description: "ID of the user"         allowEmptyValue: true         schema:           type: integer

Параметры могут быть указаны для path, query, header и cookie. Вместо schema может быть указан content для передачи сложного json’а.

Для запросов, которые поддерживают тело запроса, указывается requestBody. Все просто: указываем обязательность, описание, тип и схему контента. Также можно указать сразу на компонент из requestBodies (на практике чаще всего используется схема, так как тело запроса редко остается неизменным).

С responses тоже все относительно понятно: это список ответов на запросы, стандартные ошибки удобно вынести в компоненты и переиспользовать.Конструкции

Конструкции anyOf, oneOf, allOf

С anyOf, oneOf и вы можете указать, например, несколько вариантов тела запроса, которые он может принимать. Встречал довольно редко.

А вот allOf − это суперудобная вещь: с ее помощью можно  объединить несколько данных в одну сущность. И это позволяет, например, сложить несколько компонентов в один. Чуть ниже будет пример.

Лайфхаки

allOf

Если есть набор запросов на одну сущность, например, книги, удобнее всего описывать schemas в порядке увеличения элементов через их объединение с помощью конструкции allOf. Например, у нас есть GET-запрос, который возвращает имя и возраст пользователя. Позже у нас появляется потребность сделать POST-запрос, который добавляет еще один параметр в запросе – address. Это можно сделать через создание нового класса и объединения в нем AllOfExampleGet с новым параметром – address.

AllOfExampleGet:   type: object   properties:     name:        type: string     age:        type: integer AllOfExamplePost:   type: object   allOf:     - $ref: "#/components/schemas/AllOfExampleGet"   properties:     address:       type: integer   required:     - name

Required-поля

В примере выше можно заметить, что обязательность name была добавлена в новой схеме. И это суперудобно! Можно копипастить один и тот же класс в другие, расставляя новые требования к обязательности полей. Обязательность полей

Обязательность можно указать для конкретной схемы. Например, у есть запрос на запись и возврат, и на post запрос мы хотим сделать обязательными ряд полей. 

ChatGPT

ChatGPT хорошо переводит описания таблиц в компоненты: удобно скопировать из приложения управлением базами (DBeaver/DataGrip) содержание таблицы и попросить сформировать компоненты. Это сильно сокращает время на запросы, которые просто вытаскивают или засовывают данные из таблиц и в них.

С чего начинать описание

Я рекомендую начинать описание с компонентов, если уже есть понимание, какие запросы планируется реализовать. Это позволит сразу описать повторяющиеся элементы и сократит размер кода.

Description

Я рекомендую добавлять в описание запросов всю информацию, которая туда может только влезть. Указывать ссылку на Сonfluence, где описывается сценарий, прописывать неочевидную логику того, как у вас проверяются поля, в какую таблицу делается запись.

Инструменты

Лично мне удобнее писать в IDE. Прикладываю ссылки на VS Code. Но онлайн-эдитор тоже удобный. И там, и там подсвечиваются ошибки с довольно точным указанием на исправление.

Шаблоны

Подсмотреть, как описывается тот или иной элемент можно в шаблоне на https://editor.swagger.io/. 

Также я сделал отдельный шаблон, который может помочь при копипасте похожих элементов + в качестве небольшой подсказки: https://github.com/AlexUra/swagger-openapi-example/blob/main/example.yml

P.S. Еще у меня канал есть


ссылка на оригинал статьи https://habr.com/ru/articles/776538/

Комментарии

Добавить комментарий

Ваш адрес email не будет опубликован. Обязательные поля помечены *