Это руководство знакомит вас с областью проектирования API Schema-First и знакомит с тем, как начать работу с экосистемой OpenAPI.

Вы создаете API.

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

На следующий день в API будет добавлена ​​новая функция. Для этого вам необходимо:

  • Обновите реализацию сервера для поддержки новой функции.
  • Обновите все клиентские библиотеки (по одному SDK для каждой поддерживаемой платформы и языка).
  • Обновите документацию.
  • Все вышесказанное должно согласовываться между собой.
  • Кроме того, команда веб-интерфейса заблокирована, пока ваш API-интерфейс не будет завершен.

Вы тяжело вздохнули.

Есть способ сделать это лучше?

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

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

Вместо того, чтобы сразу переходить к разработке, мы начинаем с спецификации API.

Первоначальный дизайн API

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

Улучшенный дизайн API

Спецификации API представляют собой контракт на API.

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

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

Итерации быстрее между несколькими командами

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

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

Создавайте тесты для вашего API

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

Сгенерируйте код и документацию

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

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

Языки спецификации API

API Specification Languages ​​определяет независимое от языка стандартное представление ваших REST API. Примеры языков спецификации API включают OpenAPI, API Blueprint и RAML.

В следующем разделе мы рассмотрим язык спецификаций OpenAPI и инструменты, окружающие его.

Язык спецификации OpenAPI

Обзор

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

OpenAPI - это основанный на JSON / YAML язык спецификации API и фреймворк для описания, создания, использования и визуализации веб-сервисов RESTful. Общая цель OpenAPI - дать возможность клиентским системам и системам документации обновляться с той же скоростью, что и сервер.

В чем разница между OpenAPI и Swagger?

OpenAPI - официальное название спецификации. Разработке спецификации способствует Инициатива OpenAPI, в которой участвуют более 30 организаций из разных областей технологического мира, включая Microsoft, Google, IBM и CapitalOne. Smartbear Software, компания, возглавляющая разработку инструментов Swagger, также является членом OpenAPI Initiative, помогая руководить развитием спецификации.

Swagger - это имя, связанное с некоторыми из наиболее известных и широко используемых инструментов для реализации спецификации OpenAPI. Спецификация OpenAPI 3.0 основана на спецификации Swagger 2.0. Набор инструментов Swagger включает в себя сочетание инструментов с открытым исходным кодом, бесплатных и коммерческих инструментов, которые можно использовать на разных этапах жизненного цикла API.

OpenAPI предлагает больше, чем просто язык спецификаций, другие инструменты в экосистеме включают:

  • Редактор Swagger: редактор Swagger позволяет редактировать спецификации OpenAPI в YAML внутри вашего браузера и просматривать документацию в реальном времени.
  • Swagger UI: Swagger UI - это набор ресурсов HTML, Javascript и CSS, которые динамически создают красивую документацию из OAS-совместимого API.
  • Swagger Codegen: позволяет автоматически создавать клиентские библиотеки API (создание SDK), заглушки сервера и документацию с учетом спецификации OpenAPI.
  • Swagger Inspector: инструмент проверки API, который позволяет создавать определения OpenAPI из существующего API.

Начиная

Спецификация OpenAPI позволяет описывать API, включая (среди прочего):

  • Общая информация об API
  • Доступные пути (например, /resources)
  • Доступные операции на каждом пути (например, GET /resources/{id})
  • Ввод / вывод для каждой операции

Вот минимальная спецификация OpenAPI в YAML:

openapi: 3.0.0

info:
  title: Sample API
  description: Optional multiline or single-line description in [CommonMark](http://commonmark.org/help/) or HTML.
  version: 0.1.9

servers:
  - url: http://api.example.com/v1
    description: Optional server description, e.g. Main (production) server
  - url: http://staging-api.example.com
    description: Optional server description, e.g. Internal staging server for testing

paths:
  /users:
    get:
      summary: Returns a list of users.
      description: Optional extended description in CommonMark or HTML.
      responses:
        '200':    # status code
          description: A JSON array of user names
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string

В спецификации OpenAPI 3.0 на корневом уровне 8 разделов. Внутри этих объектов корневого уровня много вложенных объектов, но на корневом уровне есть только эти объекты:

  • openapi: Обязательно. Номер семантической версии спецификации OpenAPI, которая используется в документе OpenAPI (например, 3.0.0.)
  • info: Обязательно. Предоставляет метаданные об API.
  • servers: массив объектов сервера, которые предоставляют информацию о подключении к целевому серверу.
  • components: элемент для хранения различных схем спецификации.
  • security: Объявление о том, какие механизмы безопасности могут использоваться в API.
  • tags: список тегов, используемых в спецификации, с дополнительными метаданными.
  • externalDocs: Дополнительная внешняя документация.
  • paths: Обязательно. Доступные пути и операции для API.

Вы можете использовать онлайн-редактор Swagger Editor, чтобы следить за мной!

Давайте кратко рассмотрим каждый из приведенных выше разделов.

Объект info предоставляет метаданные об API.

info:
  title: Sample Pet Store App
  version: 1.0.1
  description: This is a sample server for a pet store.
  termsOfService: http://example.com/terms/
  contact:
    name: API Support
    url: http://www.example.com/support
    email: [email protected]
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html

Не забудьте попробовать это в онлайн-редакторе Swagger!

Раздел servers

В разделе servers указывается сервер API и базовый URL. Вы можете определить один или несколько серверов, например производственный и песочницу.

servers:
  - url: https://my-api.com
    description: Production server
  - url: https://beta.my-api.com
    description: Beta server
  - url: https://some-other.my-api.com
    description: Some other server

В пользовательском интерфейсе Swagger пользователи смогут выбирать серверы для отправки запросов из этого предопределенного списка:

Раздел components

Компоненты - это набор многократно используемых объектов для остальной части API, таких как:

Объекты схемы

Определение типов входных и выходных данных на основе JSON-схемы.

Раздел global components/schemas позволяет вам определять общие структуры данных, используемые в вашем API. На них можно ссылаться через $ ref всякий раз, когда требуется схема - в параметрах, телах запросов и телах ответов.

Например, этот объект JSON:

{
  "name": "Garfield",
  "type": "Cat"
}

можно представить как:

components:
  schemas: # Schema object definition
    Pet:
      type: object
      properties:
        name:
          type: string
        petType:
          type: string
      required:
      - name
      - petType

и упоминается в другом месте с помощью $ref: '#/components/schemas/Pet'.

Подробнее о моделях данных OpenAPI.

Объекты ответа

Ожидаемые ответы для разных кодов ответа HTTP операции.

components:
  responses:
    ListPetsSuccessResponse:
      description: A an array response with headers
      content:
        application/json:
          schema:
            type: array
            items:
              $ref: '#/components/schemas/Pet'
          headers:
            X-Rate-Limit-Limit:
              description: The number of allowed requests in the current period
              schema:
                type: integer

Объекты параметров

Параметры операций могут передаваться через URL-путь (/users/{userId}), строку запроса (/users?role=admin), заголовки (X-CustomHeader: Value) или файлы cookie (Cookie: debug=0). Вы можете определить типы данных параметров, формат, являются ли они обязательными или необязательными, а также другие детали:

# A path parameter of string value

name: username
in: path
description: username to fetch
required: true
schema:
  type: string
# A header parameter with an array of 64 bit integer numbers:
name: token
in: header
description: token to be passed as a header
required: true
schema:
  type: array
  items:
    type: integer
    format: int64

Примеры объектов

Вот пример ключевого слова example в теле ответа:

responses:
  '200':
    description: A cat object.
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/Pet'   # Reference to an object
        example:
          # Example properties of the referenced object
          name: Garfield
          type: Cat

Другие объекты-компоненты

Вы также можете определить объекты Схема безопасности, Заголовок, Ссылка (гипермедиа) и Обратный вызов (веб-перехватчик) в разделе components.

Использование components совершенно необязательно. Это наиболее полезно для хранения любых часто используемых объектов домена с возможностью повторного использования.

Все объекты, определенные в объекте компонентов, не будут влиять на API, если на них явно не ссылаются свойства вне объекта компонентов.

Раздел security

Объект security определяет протокол безопасности или авторизации, используемый при отправке запросов. OpenAPI поддерживает следующие методы аутентификации:

  • HTTP-аутентификация: базовая, на предъявителя и т. Д.
  • Ключ API в качестве заголовка или параметра запроса или в файлах cookie
  • OAuth 2
  • Открытие OpenID Connect

На корневом уровне документа OpenAPI добавьте объект безопасности, который определяет глобальный метод, который мы используем для обеспечения безопасности:

security:
- API-Key: []

В объект components мы добавляем объект securitySchemes, который определяет подробную информацию о схеме безопасности, которую мы используем:

components:
  securitySchemes:
    API-Key:
      type: apiKey
      description: "The API authorizes requests through an API key in your header."
      name: X-API-Key
      in: header

Представьте, что у вас есть API с более чем 50 путями для описания. Вы можете организовать их в логические группы, чтобы пользователи могли перемещаться по ним. Объект tags обеспечивает способ группировки путей (конечных точек) в отображении пользовательского интерфейса Swagger.

Определите свои теги на корневом уровне:

tags:
  - name: Products
    description: Handles product information.
  - name: Orders
    description: Operations for processing purchases and orders.

Затем вы можете использовать любые определенные теги в отдельных операциях:

paths:
 ...
 /products:
   get:
     ...
     tags:
     - Products
     ...

Это сгруппирует операции с одинаковыми тегами в пользовательском интерфейсе Swagger:

Вот пример объекта externalDocs:

externalDocs:
  description: Product documentation for the API
  url: https://myapi.com/docs

В пользовательском интерфейсе Swagger эта ссылка появляется после описания API вместе с другой информацией об API.

Раздел paths

В терминах OpenAPI paths - это конечные точки (ресурсы), такие как /pets или /products/summary/, которые предоставляет ваш API, а операции - это HTTP методы, используемые для управления этими путями, например GET, POST или DELETE.

Во-первых, давайте перечислим пути нашего API:

paths:
  /products:
    get:

  /orders:
    post:

Каждый объект пути (/products.get, /orders.post) - это операция. Вот полный пример:

paths:
  /products/{id}:
    get:
      tags:
        - Products
      summary: Gets a product by ID.
      description: >
        A detailed description of the operation.
        Use markdown for rich text representation,
        such as **bold**, *italic*, and [links](http://swagger.io).
      operationId: getProductById
      parameters:
        - name: id
          in: path
          description: Product ID
          required: true
          schema:
            type: integer
            format: int64
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Product'
      externalDocs:
        description: Learn more about product operations provided by this API.
        url: http://api.example.com/docs/product-operations/

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

Это все, что вам нужно для начала! Попробуйте!

После написания спецификация OpenAPI и инструменты Swagger могут способствовать дальнейшему развитию вашего API и сэкономить значительное количество времени и усилий в долгосрочной перспективе:

  • Используйте Swagger Codegen, чтобы сгенерировать заглушку сервера для вашего API. Осталось только реализовать логику сервера - и ваш API готов к работе!
  • Используйте Swagger Codegen для создания клиентских библиотек для вашего API на более чем 40 языках.
  • Используйте Swagger UI для создания интерактивной документации API, которая позволяет вашим пользователям опробовать вызовы API прямо в браузере.
  • "И более!"

В заключение

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

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

Что делать, если у меня уже есть API?

Если ваш API уже реализован (хотя бы частично), вы можете выполнять вызовы API к вашему API из Swagger Inspector. для автоматического создания файла OpenAPI для любой вызываемой конечной точки.

Дополнительное чтение

Вот несколько рекомендуемых ресурсов для дальнейшего обучения:

Первоначально опубликовано на yos.io 11 февраля 2018 г.