Swagger 2.0 в OpenAPI 3: конвертация спецификации

Многие инструменты (генераторы кода, шлюзы, линтеры) работают только с OpenAPI 3. Перевод старой спецификации Swagger 2.0 вручную — это десятки мелких правок по всему документу; конвертер делает их за один шаг.

Как перевести

1. Откройте спецификацию Swagger 2.0 в редакторе OpenAPI.
2. В меню появится пункт Файл → Преобразовать в → OpenAPI 3.0 (из Swagger 2.0) — он показывается только для документов с swagger: "2.0".
3. Посмотрите предпросмотр и сохраните результат новым артефактом (исходник останется) или откройте в песочнице.

Что меняется

Swagger 2.0	OpenAPI 3.0
host, basePath, schemes	servers: [{url: https://host/basePath}]
параметр in: body	requestBody с content по consumes
параметры in: formData	requestBody с application/x-www-form-urlencoded или multipart/form-data (если есть файл)
type, format, enum у параметров	блок schema
responses.*.schema	content по produces
definitions, parameters, responses	components/schemas, components/parameters, components/responses; все $ref переписаны
securityDefinitions	components/securitySchemes: basic → http basic, oauth2 — с потоками (flows)
x-nullable, type: file	nullable, string + format: binary

Что проверить после

• Если спецификация ссылается на другие файлы Swagger 2.0, ссылки уже указывают на разделы OpenAPI 3 — преобразуйте и те файлы (окно об этом предупредит).
• collectionFormat для query-параметров переводится в style/explode; редкие форматы (ssv, tsv, pipes) проверьте вручную.
• Примеры ответов (examples по типам содержимого) переносятся в example соответствующего content.

Результат — OpenAPI 3.0.3: его понимают практически все инструменты. Документацию результата сразу видно справа в редакторе.

Пример

Фрагмент Swagger 2.0:

swagger: "2.0"
host: api.example.com
basePath: /v1
schemes: [https]
consumes: [application/json]
paths:
  /pets:
    post:
      parameters:
        - {in: body, name: pet, required: true, schema: {$ref: "#/definitions/Pet"}}

После преобразования:

openapi: 3.0.3
servers:
  - url: https://api.example.com/v1
paths:
  /pets:
    post:
      requestBody:
        required: true
        content:
          application/json:
            schema: {$ref: "#/components/schemas/Pet"}

Вопросы и ответы

Почему 3.0, а не 3.1? 3.0.3 поддерживают практически все генераторы, шлюзы и валидаторы. Переход 3.0 → 3.1 касается в основном схем (nullable → тип с null, example → examples) и делается точечно.

Можно ли перевести спецификацию из нескольких файлов? Да, каждый файл переводится отдельно; ссылки в главном файле уже указывают на разделы OpenAPI 3 в связанных файлах, поэтому преобразуйте и их.