OpenApi

Введение

The OpenAPI Specification (с англ.—«спецификация OpenAPI»; изначально известная как Swagger Specification) — формализованная спецификация и экосистема множества инструментов, предоставляющая интерфейс между front-end системами, кодом библиотек низкого уровня и коммерческими решениями в виде API.

Вместе с тем, cпецификация построена таким образом, что не зависит от языков программирования, и удобна в использовании как человеком, так и машиной.

Относительно назначения, OpenAPI рассматривается как универсальный интерфейс для пользователей (клиентов) по взаимодействию с сервисами (серверами).

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

Для этих действий имеется большой набор инструментов для различных языков программирования и платформ.

Изначально разработка спецификации под названием Swagger Specification проводилась с 2010 года компанией SmartBear.

В ноябре 2015 года SmartBear объявила, что она работает над созданием новой организации Open API Initiative при спонсорской поддержке Linux Foundation. 1 января 2016 года спецификация была переименована в The OpenAPI Specification, а её развитие ведётся в рамках Open API Initiative.

One Of

Выбор из фиксированных вариантов осуществляется с помощью codeGen namedEnum oneOf.

У объекта Value однин из атрибутов - filters может принимать значения 1, 2 или 3.

Value: properties: something: type: number format: double title: Some Title examples: [ 0 ] filters: $ref: "#/components/schemas/Filters" Filters: type: integer format: int32 maximum: 2 codeGen: namedEnum oneOf: - const: 1 title: One description: First - const: 2 title: Two description: Second - const: 3 title: Three description: Third

Массивы

Если запрос или ответ по своей структуре является массивом. Например

[ { "site": { "metadata": { "name": "TestSetup", "established": 2023, "major": "Software Testing" }, "url": "https://testsetup.site" }, "topics": [ { "robot": { "architecture": 5, "variables": 2 } }, { "pytest": { "skeleton": 1, "parametrize": 1 } } ] } ]

Для корректного отображения нужно создать верхнеуровневый объект типа array весь смысл которого - показать OpenAPI что в корне будет именно квадратная скобка а не фигурная.

Этот объект в поле items должен ссылаться на другой объект - тот в котором и будет отображена основная структура. Например

SitesRequest: title: Sites request type: array items: $ref: '#/components/schemas/SitesRequestItem' SitesRequesItem: title: Sites request item properties: site: … topics: …

servers

Можно одновременно указать несколько адресов на который OpenAPI клиент будет отправлять запросы. Каждый адрес может иметь несколько доступных портов. Пример:

servers: - url: http://localhost variables: port: enum: - '443' - '9801' default: '9801' - url: / variables: port: enum: - '443' - '9801' default: '443'

Валидаторы

Для версий от 3.1 editor-next.swagger.io

Автор статьи: Андрей Олегович