Зарегистрируйтесь для доступа к 15+ бесплатным курсам по программированию с тренажером

OpenAPI (ранее Swagger Specification) HTTP API

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

Это приводит к большому количеству проблем, которые легко решаются в RPC протоколах:

  • Документация описывается вручную и в каждом 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 создайте документацию для вашего API, которое создали ранее (список пользователей). При выполнении этого задания пользуйтесь гайдом по структуре. Также вам будет полезен онлайн-редактор

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

  1. Postman позволяет не только удобно работать с API, используя коллекции, но и импортировать OpenAPI спецификацию для создания коллекции. Импортируйте получившийся файл в Postman и проверьте, что запросы выполняются успешно.


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

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

Аватары экспертов Хекслета

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

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

Для полного доступа к курсу нужен базовый план

Базовый план откроет полный доступ ко всем курсам, упражнениям и урокам Хекслета, проектам и пожизненный доступ к теории пройденных уроков. Подписку можно отменить в любой момент.

Получить доступ
900
упражнений
2000+
часов теории
3200
тестов

Открыть доступ

Курсы программирования для новичков и опытных разработчиков. Начните обучение бесплатно.

  • 130 курсов, 2000+ часов теории
  • 900 практических заданий в браузере
  • 360 000 студентов
Даю согласие на обработку персональных данных, соглашаюсь с «Политикой конфиденциальности» и «Условиями оказания услуг»

Наши выпускники работают в компаниях:

Логотип компании Альфа Банк
Логотип компании Aviasales
Логотип компании Yandex
Логотип компании Tinkoff
Рекомендуемые программы

С нуля до разработчика. Возвращаем деньги, если не удалось найти работу.

Иконка программы Фронтенд-разработчик
Профессия
Разработка фронтенд-компонентов веб-приложений
30 июня 10 месяцев
Иконка программы Python-разработчик
Профессия
Разработка веб-приложений на Django
30 июня 10 месяцев
Иконка программы PHP-разработчик
Профессия
Разработка веб-приложений на Laravel
30 июня 10 месяцев
Иконка программы Node.js-разработчик
Профессия
Разработка бэкенд-компонентов веб-приложений
30 июня 10 месяцев
Иконка программы Fullstack-разработчик
Профессия
Новый
Разработка фронтенд и бэкенд компонентов веб-приложений
30 июня 16 месяцев
Иконка программы Java-разработчик
Профессия
Разработка приложений на языке Java
30 июня 10 месяцев

Используйте Хекслет по максимуму!

  • Задавайте вопросы по уроку
  • Проверяйте знания в квизах
  • Проходите практику прямо в браузере
  • Отслеживайте свой прогресс

Зарегистрируйтесь или войдите в свой аккаунт

Даю согласие на обработку персональных данных, соглашаюсь с «Политикой конфиденциальности» и «Условиями оказания услуг»

Изображение Тото

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