OpenAPI станет проще: готовится версия 4.0

Сегодня OpenAPI считается стандартом де-факто для описания программных интерфейсов. Основной смысл этих спецификаций в том, что и документация, и серверный интерфейс API генерируются автоматически на основании схемы OpenAPI. Во-первых, это гарантирует актуальность документации и её соответствие реально используемым методам. Во-вторых, сильно облегчает жизнь потребителям API, у которых автоматически генерируется клиентский код.

До появления расширения OpenAPI DevTools проектировать схему OpenAPI приходилось вручную. Хотя это было непросто, оно того стоит в любом случае. Недавно мы в RUVDS переделали свой API под данный стандарт — и увидели, насколько это эффективно и полезно для всех пользователей и разработчиков, которые обращаются к серверным API.

Сейчас в разработке находится четвёртая версия OpenAPI. Она станет проще и универсальнее, то есть подойдёт даже для тех HTTP API, для которых не годится текущая версия 3.0 (3.1.0).

Основную причину для реализации OpenAPI все хорошо знают. Спецификация определяет стандартное, не зависящее от языка программирования описание интерфейса для HTTP API, которое позволяет людям и компьютерам обнаружить и понять возможности сервиса, не требуя доступа к исходному коду, дополнительной документации или изучения сетевого трафика. При правильном определении через OpenAPI потребитель может понять и взаимодействовать с удалённым сервисом с минимальным количеством логики реализации.

Комментарий от наших разработчиков:

Сейчас для добавления или изменения нового метода в API RUVDS первым делом изменяется схема OpenAPI. После этого на основании новой схемы:

• генерируется интерфейс для серверной части API и реализуются методы;
  
• генерируется документация;
  
• клиент на основании схемы может генерировать заготовки клиента для множества языков программирования.

Такой подход позволяет поддерживать соответствие документации и реальной реализации с минимальными затратами. Сгенерированные заготовки кода сокращают время разработки клиента для подключения.

Раньше мы работали по старинке: сначала реализовывали методы в серверной части, а потом вручную добавляли их описание в документацию.

Недостатки старого подхода очевидны: документация может не соответствовать реальным методам. При этом клиент читает документацию и реализовывает подключение без возможности получения примеров кода. Сейчас стало на порядок удобнее.

▍ Спецификации OpenAPI

Текущая версия OpenAPI v3.1.0 принята в феврале 2021 года.

Как уже упоминалось, эти спецификации (прежнее название Swagger) стали стандартом де-факто для описания HTTP API. В одном файле описываются все параметры взаимодействия с сервисом. В секции серверов описано, куда идут обращения (начальные пути URL серверов API). В списке путей (paths) — конечные точки, к которым идёт обращение, они содержат в себе запросы и возможные ответы. В секции компонентов (components) — схемы и параметры, совместно используемые в точках доступа, и т. д. Всё довольно логично и понятно.


Спецификации в формате YAML или JSON не привязаны к языку программирования, на котором написан сам API. Эти форматы позволяют легко обмениваться спецификациями и использовать их. Файлы удобны в чтении и использовании как человеком, так и машиной.

Пример шаблона спецификаций в формате JSON:

{
  "openapi": "3.1.0",
  "info": {
    "title": "Non-oAuth Scopes example",
    "version": "1.0.0"
  },
  "paths": {
    "/users": {
      "get": {
        "security": [
          {
            "bearerAuth": [
              "read:users",
              "public"
            ]
          }
        ]
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "jwt",
        "description": "note: non-oauth scopes are not defined at the securityScheme level"
      }
    }
  }
}

С помощью такого файла можно быстро понять, как работает API сервиса и какие у него возможности. Разработчики могут использовать спецификации OpenAPI для настройки своей инфраструктуры, генерации клиентского кода и создания тестовых примеров.

Чем понятнее спецификации API — тем лучше всем. Каждый сервис заинтересован в том, чтобы его программные интерфейсы использовались как можно активнее. С другой стороны, каждый потребитель желает более понятных и ясных спецификаций, с которыми удобнее работать.

Благодаря OpenAPI потребителю не требуется разбираться в архитектуре сервиса, устройстве приложения или пытаться выучить Lisp или Haskell, если наши API написаны на этом языке. Достаточно взглянуть на файл JSON, написанный на простом и выразительном языке.

Спецификация обеспечивает именно такую передачу знаний от поставщика API к потребителю API. Это открытый стандарт, который содержит полный словарь терминов, отражающий общепринятые понятия в мире API, и включает в себя основы HTTP и JSON.

Предоставление и использование документа OpenAPI — очень важное действие, которое является основополагающим для всего жизненного цикла API, начиная от разработки и заканчивая развёртыванием и поддержкой. Если жизненный цикл API рассматривать как транспортную сеть, то OpenAPI — это главная артерия, которая предоставляет средства для эффективной передачи больших объёмов нужной информации быстро и эффективно. Эти спецификации можно использовать на каждом этапе этого жизненного цикла API:


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

С одной стороны, разработчики просят увеличить количество описаний для поддержки большего числа сценариев. В то же время другие сетуют на то, что OpenAPI стал слишком сложным для ручной разработки. В общем, четвёртая версия должна решить все эти проблемы.

▍ Изменения в OpenAPI v4

Предложение OpenAPI v4 (aka Moonwalk) пока находится в стадии обсуждения и может сильно измениться ближе к финальной версии. Однако первые отзывы на него положительные, поэтому разработчики уверены, что двигаются в правильном направлении.

Идея изменений в новой версии — упростить схему OpenAPI и в то же время сделать её более гибкой. Это попытка лучше учитывать существующие стандарты и свести к минимуму добавление новой функциональности. Суть изменённой модели показана на диаграмме:



Главное новшество OpenAPI v4 — упрощение схемы. Это основная проблема, на которую жалуются нынешние пользователи OpenAPI v3. Как видно на диаграмме вверху, упрощённая схема основана на трёх основных структурных компонентах: pathItem, request и response.

Кроме упрощения конструкции, при разработке четвёртой версии принимались в расчёт следующие задачи:

• Поддержка API, которые отдают разные ответы в зависимости от параметров запроса, заголовков и тела запроса.
  
• Поддержка более широкого спектра шаблонов проектирования URL.
  
• Сокращение вложенных структур для улучшения читабельности и редактируемости.
  
• Улучшение возможности повторного использования шаблонов запросов и ответов.

Из официального анонса:

Сейчас у элемента pathItem есть свой набор операций, по одной для каждого поддерживаемого HTTP-метода. В такой конструкции имеется неявное предположение, что HTTP-метод в пути может описывать только одно взаимодействие с одним и тем же набором ответов.

В OpenAPI v4, напротив, реализованы минимальные ограничения на то, сколько различных типов запросов может быть выполнено на одном пути. Практически любую часть запроса можно использовать для сигнализации об уникальном наборе ответов.

Если в OpenAPI v3 ключ для объекта pathItem был ограничен только частью пути в URL, то в четвёртой версии ключами pathItem могут быть полные шаблоны URI. Это позволит использовать параметры запроса для идентификации ресурса и соответствующих запросов, а также устранит необходимость в определении параметров, содержащих информацию о сериализации, поскольку шаблон URI может полностью описать, как сериализовать параметры шаблона. Использование интернет-стандарта сократит объём работы для поддержки построения URL со стороны инструментария. Это может решить давнюю проблему однозначного соотнесения URL с соответствующим pathItem.

Как видим, изменения значительные.

Пример простого описания в OpenAPI 4.0:

openapi: 4.0.0
info:
  title: Simplest thing that works
  version: 0.5.0
paths:
  "speakers":
    requests:
      createSpeaker:
        method: post
        contentType: application/json
        contentSchema:
          $ref: "#/components/schemas/speaker"
        responses:
          created:
            status: 201
      getSpeakers:
        method: get
        responses:
          ok:
            status: 200
            contentType: application/json
            contentSchema:
              type: array
              items:
                $ref: "#/components/schemas/speaker"
    pathResponses:
      notFound:
        status: 404
        contentType: application/http-problem
apiResponses:
  serverError:
    status: 5XX
    contentType: application/http-problem
components:
  schemas:
    Speaker:
      type: object
      properties:
        name: 
          type: string

То же самое в OpenAPI 3.1.0:

openapi: 3.1.0
info:
  title: Simplest thing that works
  version: 0.5.0
paths:
  "/speakers":
    post:
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/speaker"
      responses:
        201:
          description: created
        404:
          description: notFound
          content:
            application/http-problem: {}
        5XX:
          description: serverError
          content:
            application/http-problem: {}

    get:
      responses:
        200:
          description: retrieved
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/speaker"
        404:
          description: notFound
          content:
            application/http-problem: {}
        5XX:
          description: serverError
          content:
            application/http-problem: {}
components:
  schemas:
    Speaker:
      type: object
      properties:
        name: 
          type: string

В варианте OpenAPI 4.0 на 20% меньше строк и на один уровень вложенности меньше. То есть описание реально стало проще.

Осталось подождать утверждения и принятия четвёртой версии. Мы видим, насколько эффективно и удобно использование стандартных интерфейсов OpenAPI. Благодаря внедрению открытого стандарта пользователь может быстро понять, как работает API, настроить инфраструктуру и сгенерировать клиентский код. Реализация OpenAPI у нас оказалась очень удачным решением. Остаётся пожелать, чтобы все остальные инфраструктурные сервисы тоже внедрили открытый стандарт для всеобщей пользы.

Скидки, итоги розыгрышей и новости о спутнике RUVDS — в нашем Telegram-канале