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

OpenAPI HTTP API

OpenAPI (раньше Swagger) — это спецификация, которая описывает структуру API, определяя, как различные компоненты API взаимодействуют друг с другом и с внешними системами. Основная идея OpenAPI заключается в том, чтобы обеспечить единый формат для описания API, который будет понятен как людям, так и машинам. Ниже пример описания части API проекта https://code-basics.com с помощью OpenAPI в yaml-формате.

openapi: 3.0.0
info:
  title: Code Basics
  version: 1.0.0
servers:
  - url: https://code-basics.com
paths:
  /api/languages: # Описываемый путь
    get:
      summary: Languages
      responses:
        "200": # Описание ответа при коде 200
          description: Successful response
          content:
            application/json:
              schema: # Структура возвращаемых данных в json
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object

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

Зачем нужен OpenAPI

Генерация документации

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

Пример OpenAPI

Генерация клиентских SDK

OpenAPI спецификация позволяет автоматически создавать клиентские библиотеки (SDK) на различных языках программирования. Например, используя инструмент OpenAPI Generator, можно сгенерировать SDK для Python, Java, JavaScript или другого языка, что значительно упростит интеграцию с API для разработчиков, работающих с этими языками. Это избавляет от необходимости вручную писать код для взаимодействия с API.

// Гипотетический пример
import codebasics from "@hexlet/code-basics-sdk";

const languages = await codebasics.listLanguages();

Тестирование API

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

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

Пример OpenAPI

Мокирование сервиса

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

Пример OpenAPI

Элементы спецификации OpenAPI

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

openapi

Элемент openapi определяет версию спецификации OpenAPI, которую вы используете. Это обязательное поле, которое указывает на то, какую версию стандарта вы применяете для описания API.

openapi: 3.0.0

info

Раздел info содержит общую информацию о вашем API. Он должен включать минимум три обязательных поля: title, version, и description.

info:
  title: Sample API
  description: This is a sample API to demonstrate OpenAPI elements.
  version: 1.0.0

paths

Раздел paths описывает доступные пути вашего API и методы, которые могут быть вызваны по этим путям. Каждый путь должен содержать хотя бы один HTTP метод.

paths:
  /users:
    get:
      summary: Retrieve a list of users
      responses:
        '200':
          description: A JSON array of user names
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string

responses

Каждый путь и метод в разделе paths должны иметь хотя бы одно определение responses, которое указывает, что возвращает API в ответ на запрос. Минимально требуется указать код ответа (например, 200 для успешного ответа) и его описание.

responses:
  '200':
    description: A list of users

Пример минимальной спецификации OpenAPI

openapi: 3.0.0
info:
  title: Sample API
  description: This is a sample API to demonstrate OpenAPI elements.
  version: 1.0.0
paths:
  /users:
    get:
      summary: Retrieve a list of users
      responses:
        '200':
          description: A JSON array of user names
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string

Этот пример включает все обязательные элементы: версию OpenAPI, базовую информацию о сервисе, описание доступного пути /users и метод get, а также описание ответа на успешный запрос. Валидация этой спецификации пройдет успешно, и её можно будет использовать в инструментах для генерации документации, тестирования и других задач.

Создание спецификации OpenAPI

Существует несколько подходов и инструментов для создания спецификации. Рассмотрим некоторые из них.

Code-First vs Design-First

  • При использовании Code-First подхода спецификация OpenAPI генерируется на основе существующего кода. Это может быть удобно, если API уже реализован, и нужно создать его документацию и спецификацию. Многие фреймворки и библиотеки (например, SpringDoc для Java или Swashbuckle для .NET) могут автоматически генерировать спецификацию на основе аннотаций в коде. Такой подход гарантирует, что спецификация всегда синхронизирована с реализацией API. Этим занимаются разработчики.
  • Design-First подход предполагает, что сначала создается спецификация, а потом на её основе пишется код. Это позволяет лучше продумывать архитектуру API заранее. Для этого используются онлайн-редакторы, такие как Swagger Editor или Stoplight Studio. В них можно создавать и редактировать спецификацию OpenAPI в удобном интерфейсе, визуально представляя структуру API и его эндпоинты.

Формат

Спецификации OpenAPI могут быть записаны в двух форматах: YAML и JSON.

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

{
  "openapi": "3.0.0",
  "info": {
    "title": "My API",
    "version": "1.0.0"
  },
  "paths": {
    "/users": {
      "get": {
        "summary": "Get a list of users",
        "responses": {
          "200": {
            "description": "A JSON array of user objects"
          }
        }
      }
    }
  }
}

Хранение и обновление

Спецификация OpenAPI должна быть версионирована и храниться в системе контроля версий, такой как Git. Это позволяет отслеживать изменения, вносить обновления и совместно работать над спецификацией. Файл со спецификацией (обычно openapi.yaml или openapi.json) размещается в репозитории вместе с исходным кодом API.

Хранение спецификации OpenAPI на Github

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

Документация

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

  • Swagger UI позволяет визуализировать и взаимодействовать с API в браузере на основе спецификации OpenAPI. Он предоставляет пользователю удобный интерфейс для изучения всех эндпоинтов и их параметров.
  • ReDoc генерирует статическую документацию из спецификации OpenAPI. Этот инструмент также предоставляет множество настроек для кастомизации внешнего вида документации.
  • Stoplight и другие коммерческие платформы предоставляют более продвинутые возможности для создания, хранения и публикации документации с интеграцией CI/CD и возможностями для совместной работы.

Документация OpenAPI сгенерированная с помощью ReDoc

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


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

У проекта code-basics тоже есть свой API. В репозитории по ссылке находится его OpenAPI спецификация в yaml формате.

  • Откройте спецификацию и изучите ее. Посмотрите, какие элементы в ней есть. Эта спецификация сгенерирована на основании существующего кода
  • Скачайте файл спецификации себе, он понадобится нам для работы

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

  • Откройте редактор и загрузите туда спецификацию. Изучите сгенерированную документацию
  • Попробуйте выполнить несколько запросов к эндпоинтам

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

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

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

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

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

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

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

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

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

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

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

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

Логотип компании Альфа Банк
Логотип компании Aviasales
Логотип компании Yandex
Логотип компании Tinkoff
Рекомендуемые программы
профессия
от 25 000 ₸ в месяц
Разработка фронтенд-компонентов для веб-приложений
10 месяцев
с нуля
Старт 14 ноября
профессия
от 25 000 ₸ в месяц
Разработка веб-приложений на Django
10 месяцев
с нуля
Старт 14 ноября
профессия
от 14 960 ₸ в месяц
Ручное тестирование веб-приложений
4 месяца
с нуля
Старт 14 ноября
профессия
от 25 000 ₸ в месяц
Разработка приложений на языке Java
10 месяцев
с нуля
Старт 14 ноября
профессия
от 25 000 ₸ в месяц
Разработка веб-приложений на Laravel
10 месяцев
с нуля
Старт 14 ноября
профессия
от 39 525 ₸ в месяц
Разработка фронтенд- и бэкенд-компонентов для веб-приложений
16 месяцев
с нуля
Старт 14 ноября
профессия
от 25 000 ₸ в месяц
Разработка бэкенд-компонентов для веб-приложений
10 месяцев
с нуля
Старт 14 ноября
профессия
новый
Автоматизированное тестирование веб-приложений на JavaScript
8 месяцев
c опытом
Старт 14 ноября

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

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

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

Отправляя форму, вы принимаете «Соглашение об обработке персональных данных» и условия «Оферты», а также соглашаетесь с «Условиями использования»