OpenAPI — HTTP API

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

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

Это приводит к множеству проблем. В REST API нет:

• Единого стандарта оформления документации
• Автоматической проверки корректности вызовов и входящих параметров
• Генерации кода тестов
• Структур данных в языке для работы с данными API
• Статического анализа и подсветки неправильных запросов в редакторе

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

С его помощью выполняется автоматическая генерация документации, тестов, кода для выполнения запросов и проверки корректности данных:

# OpenAPI-описание удобнее всего записывать в yaml-формате
# Пример зоомагазина

openapi: "3.0.0"
info:
  version: 1.0.0
  title: Swagger Petstore
  license:
    name: MIT
servers:
  - url: http://petstore.swagger.io/v1
paths:
  /pets:
    get:
      summary: List all pets
      operationId: listPets
      tags:
        - pets
      parameters:
        - name: limit
          in: query
          description: How many items to return at one time (max 100)
          required: false
          schema:
            type: integer
            format: int32
      responses:
        '200':
          description: A paged array of pets
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Pets"
    post:
      summary: Create a pet
      operationId: createPets
      tags:
        - pets
      responses:
        '201':
          description: Null response
  /pets/{petId}:
    get:
      summary: Info for a specific pet
      operationId: showPetById
      tags:
        - pets
      parameters:
        - name: petId
          in: path
          required: true
          description: The id of the pet to retrieve
          schema:
            type: string
      responses:
        '200':
          description: Expected response to a valid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Pet"
components:
  schemas:
    Pet:
      type: object
      required:
        - id
        - name
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string
        tag:
          type: string
    Pets:
      type: array
      items:
        $ref: "#/components/schemas/Pet"

Здесь мы видим набор эндпоинтов, в которых определяется структура и ожидаемых на вход параметров, и выходных данных.

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

Самостоятельная работа

Дополнительные материалы

1. Спецификация OpenAPI

---

Остались вопросы? Задайте их в разделе «Обсуждение»

Вам ответят команда поддержки Хекслета или другие студенты

Об обучении на Хекслете

• Статья «Как учиться и справляться с негативными мыслями»
• Статья «Ловушки обучения»
• Статья «Сложные простые задачи по программированию»
• Вебинар «Как самостоятельно учиться»