Что такое OpenAPI?

OpenAPI — это стандарт для описания вычислительных интерфейсов, известных как API (интерфейсы прикладного программирования). Спецификация OpenAPI определяет открытый, нейтральный к производителям формат описания сервисов API. OpenAPI позволяет разработчикам описывать, разрабатывать, тестировать и документировать REST-совместимые API.

Спецификация OpenAPI стала результатом проекта Swagger. Компания-разработчик SmartBear решила сделать Swagger Specification доступной по лицензии с открытым исходным кодом и передала ее поддержку и дальнейшее развитие OpenAPI Initiative. Помимо SmartBear, в состав участников OpenAPI Initiative входят такие тяжеловесы индустрии, как Google, IBM и Microsoft. Проект также спонсируется Linux Foundation.

OpenAPI — обзор

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

OpenAPI предоставляет разработчикам стандартизированный способ описания API. Описание называется «определением API» и создается в машиночитаемом формате. Наиболее используемыми языками являются YAML и JSON.

Примечание

Помимо «определения API», вы также можете встретить термин «спецификация API». Оба они представляют собой абстрактное описание API, но последнее создается исключительно для человеческого читателя.

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

# YAML
servers:
- url: https://development.example.com/v1
  description: Development server
- url: https://staging.example.com/v1
  description: Staging server
- url: https://api.example.com/v1
  description: Production server
// JSON
{
  "servers": [
    {
      "url": "https://development.example.com/v1",
      "description": "Development server"
    },
    {
      "url": "https://staging.example.com/v1",
      "description": "Staging server"
    },
    {
      "url": "https://api.example.com/v1",
      "description": "Production server"
    }
  ]
}

Спецификация OpenAPI определяет несколько свойств, которые используются для создания API. Эти свойства сгруппированы вместе как «объекты». Текущая версия OpenAPI (3.0.3) определяет структуру для следующих объектов (среди прочих):

  • Информационный объект: Версия API, имя и т.д.
  • Контактный объект: Контактная информация для поставщика API
  • Объект License: Лицензия, на основании которой API предоставляет свои данные
  • Объект сервера: Имя хоста, структура URL и порты сервера, через который осуществляется доступ к API.
  • Объект компонентов: Многократно используемые компоненты, которые могут быть использованы более одного раза в определении API
  • Объект Paths: Относительные пути к конечным точкам API, которые используются в сочетании с объектом Server.
  • Объект Path Item Object: Операции, разрешенные для определенного пути, такие как GET, PUT, POST, DELETE.
  • Объект операции: Определяет (среди прочего) параметры и ожидаемые ответы сервера для операции.

Где используется OpenAPI?

В целом, OpenAPI используется для описания REST API в стандартизированной манере. Благодаря тому, что описание (определение API) доступно в машиночитаемом формате, на его основе могут быть автоматически сгенерированы различные виртуальные артефакты. К ним относятся:

  • Документация API: Документация на основе HTML может быть автоматически сгенерирована из машиночитаемого определения API. Разработчики, работающие с сервисами API, могут использовать ее в качестве справочной документации. Если определение API изменяется, документация регенерируется таким образом, чтобы она отражала последнее определение.
  • Код на различных языках программирования: С помощью специального инструмента из определения API можно сгенерировать библиотеку программного обеспечения на стороне клиента на поддерживаемом языке программирования. Это означает, что доступ к API могут получить программисты с любым уровнем подготовки. Программная библиотека интегрируется обычным способом. Затем доступ к службам API можно получить через вызов функций в обычной среде программирования.
  • Тестовые случаи: Каждый компонент программного обеспечения должен быть протестирован, чтобы убедиться, что он работает правильно. Более того, компоненты программного обеспечения должны быть заново протестированы при каждом изменении основного кода. Благодаря определению API эти тестовые случаи могут быть автоматически сгенерированы, чтобы можно было тщательно проверить функции программных компонентов.

Для полноты картины следует отметить, что не каждый API может быть определен с помощью OpenAPI. Однако существует явная поддержка REST API.

Каковы преимущества OpenAPI?

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

Помимо этих общих преимуществ, OpenAPI особенно полезен тем, что предоставляет стандартизированный способ разработки REST API. Это очень полезно, поскольку, хотя REST-совместимые API имеют ряд преимуществ, разработать их вручную не так-то просто. REST работает по протоколу HTTP/S, и необходимые порты открыты во всех брандмауэрах.

Другие полезные возможности OpenAPI включают:

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

Сколько существует версий OpenAPI и в чем разница между ними?

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

Версия Название Статус
1.0, август 2011 г. Спецификация Swagger Больше не используется
2.0, сентябрь 2014 г. Спецификация Swagger > Спецификация OpenAPI Все еще поддерживается
3.0, июль 2017 г. Спецификация OpenAPI По-прежнему поддерживается

В приведенных ниже пунктах объясняются основные новые возможности, добавленные в версии 3.0:

Новое имя для корневого объекта

С выходом версии 3.0 объект Swagger был заменен на объект OpenAPI:

# <= 2.0
"swagger": "2.0"
# >= 3.0
"OpenAPI": "3.0.0"

Несколько хостов/серверов

В OpenAPI 3.0 к API можно обращаться более чем через один сервер. Также можно определять части URL сервера как переменные. Например:

"servers": [
    {
      "url": "https://{username}.example.com:{port}/{basePath}",
      "description": "The production API server",
      "variables": {
        "username": {
          "default": "demo",
          "description": "this value is assigned by the service provider, in this example `example.com`"
        },
        "port": {
          "enum": [
            "8443",
            "443"
          ],
          "default": "8443"
        },
        "basePath": {
          "default": "v2"
        }
      }
    }
  ]

Новые объекты Components Object и Reference Object

Одной из наиболее важных новых возможностей в OpenAPI версии 3.0 является добавление объектов Components Object и Reference Object. Components Object позволяет разработчикам определять несколько объектов, которые могут быть повторно использованы в рамках определения API. Известные как компоненты, они интегрируются в определение API с помощью специальной конструкции $ref.

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

  1. Схема репозитория кода GitHub, определенная как объект Components Object
  2. Определение лицензии, на которое ссылаются через компонент, определенный извне
"components": {
  "schemas": {
    // Repository Schema
    "repository": {
      "title": "Repository",
      "description": "A git repository",
      "type": "object",
      "properties": {
        "id": {
          "description": "Unique identifier of the repository",
          "example": 42,
          "type": "integer"
        },
        "node_id": {
          "type": "string",
          "example": "MDEwOlJlcG9zaXRvcnkxMjk2MjY5"
        },
        "name": {
          "description": "The name of the repository.",
          "type": "string",
          "example": "Team Environment"
        },
        "full_name": {
          "type": "string",
          "example": "octocat/Hello-World"
        },
        // License Definition
        "license": {
          "nullable": true,
          "allOf": [
            {
              // Reference to externally defined components
              "$ref": "#/components/schemas/license-simple"
            }
          ]
        },

Использование OpenAPI: Два примера

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

REST API GitHub v3

Популярный сервис Git, GitHub, использует OpenAPI для описания своего «GitHub v3 REST API». Определение API доступно на GitHub в виде репозитория. Оно позволяет пользователям точно определить, к каким сервисам можно получить доступ через API GitHub и как должны быть структурированы соответствующие вызовы. Кроме того, любой желающий может использовать API вместе с совместимыми инструментами для генерации кода для него.

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

В целях совместимости GitHub предоставляет определение API в нескольких форматах. Один из них — это «пакетная» версия. Она содержит компоненты, представленные с помощью OpenAPI 3.0, и ссылки на них. В качестве альтернативы существует версия «dereferenced», без ссылок. Из-за избыточности определение API с отсылками примерно в три раза больше, чем пакетная версия. Тем не менее, эта версия без ссылок очень полезна, поскольку многие инструменты еще не поддерживают ссылки.

Вы можете изучить определение API самостоятельно. Обратите внимание, однако, что полный файл имеет размер несколько мегабайт. Для текстового файла это огромный объем информации. GitHub не может отобразить такой большой файл напрямую. Однако по приведенной ниже ссылке вы можете просмотреть GitHub REST API в своем браузере. Это версия YAML, которая намного компактнее и легче для чтения: GitHub REST API (YAML).

Пример API Petstore из SwaggerHub

Этот второй пример — образец API, который можно сгенерировать на SwaggerHub. SwaggerHub — это онлайн-платформа для проектирования и разработки REST API с использованием OpenAPI. Вы можете либо создать бесплатную учетную запись пользователя, либо использовать существующую учетную запись GitHub.

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

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

Вы можете многое узнать о том, как работает OpenAPI, изучив API petstore. Определение petstore также является хорошим примером того, как построить REST-совместимый API. Наконец, давайте посмотрим на некоторый код из API petstore:

  1. Он определяет конечную точку API ‘/pet’.
  2. Используя HTTP POST запрос, вы можете добавить новое животное в зоомагазин.
  3. Если вместо этого вы используете HTTP-глагол PUT на той же конечной точке, вы можете изменить существующее животное.
  4. Для этих операций определены различные ответы сервера. В этом примере коды состояния HTTP включают хорошо известную ошибку «404 Not Found». В API petstore это представлено как «Питомец не найден».
Примечание

Строки кода, начинающиеся с ‘$ref’ и прокомментированные «OpenAPI 3.0+ Component», являются ссылками на индивидуально определенные компоненты OpenAPI.

# Petstore API Template #
# API Endpoint '/pet'
/pet:
  # HTTP-POST Request
  post:
    tags:
      - pet
    summary: Add a new pet to the store
    operationId: addPet
    # HTTP-Status codes
    responses:
      '405':
        description: Invalid input
    security:
      # Permissions
      - petstore_auth:
        - 'write:pets'
        - 'read:pets'
    requestBody:
      # OpenAPI 3.0+ Component
      $ref: '#/components/requestBodies/Pet'
  # HTTP-PUT Request
  put:
    tags:
      - pet
    summary: Update an existing pet
    operationId: updatePet
    # HTTP-Status codes
    responses:
      '400':
        description: Invalid ID supplied
      '404':
        description: Pet not found
      '405':
        description: Validation exception
    security:
      # Permissions
      - petstore_auth:
        - 'write:pets'
        - 'read:pets'
    requestBody:
      # OpenAPI 3.0+ Component
      $ref: '#/components/requestBodies/Pet'
Резюме

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

Оцените статью
cdelat.ru
Добавить комментарий