OpenAPI (раньше Swagger) — это спецификация, которая задаёт единый формат для описания API: какие запросы API принимает, какие данные возвращает и как его компоненты взаимодействуют друг с другом. Когда говорят "спецификация OpenAPI", имеют в виду как сам стандарт OpenAPI, так и документ (например, файл openapi.yaml), который описывает конкретный API на основе этого стандарта. Спецификация не является реализацией API — она лишь формально описывает, как 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 (GET, POST и т.д.), используемых в этих запросах, передаваемых параметрах запроса и форматах данных, с которыми работает API. Всё это объединено в одном документе, который можно использовать для множества разных целей.
Зачем нужен OpenAPI
Генерация документации
С помощью OpenAPI спецификации можно автоматически генерировать подробную и интерактивную документацию для вашего API. Документация API — это человекочитаемое описание, которое показывает, как взаимодействовать с API. Например, инструменты вроде Swagger UI или ReDoc могут преобразовать спецификацию в удобную для чтения веб-страницу, где разработчики могут видеть все доступные эндпоинты, параметры запросов, примеры ответов и другие детали. Это особенно полезно для команд, работающих над проектом, и для сторонних разработчиков, которые будут использовать API.
Генерация клиентских 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 можно создавать мок-сервисы, которые симулируют поведение реального API. Это полезно для разработки и тестирования, когда реальный API еще не готов или недоступен. Например, используя инструменты вроде Prism, можно быстро развернуть мок-сервис, который будет возвращать ответы на основе OpenAPI спецификации. Это позволяет разработчикам начать интеграцию с API до того, как он будет полностью реализован.
Элементы спецификации 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.
Важно регулярно обновлять спецификацию по мере внесения изменений в API. При использовании Code-First подхода обновление происходит автоматически при изменении кода, тогда как в случае с Design-First обновление спецификации вручную становится критически важным.
Документация
После того как спецификация создана и протестирована, следующим шагом является публикация документации API. Для этого спецификация OpenAPI используется для генерации человекочитаемой документации. Существует несколько популярных инструментов для публикации документации:
- Swagger UI позволяет визуализировать и взаимодействовать с API в браузере на основе спецификации OpenAPI. Он предоставляет пользователю удобный интерфейс для изучения всех эндпоинтов и их параметров.
- ReDoc генерирует статическую документацию из спецификации OpenAPI. Этот инструмент также предоставляет множество настроек для кастомизации внешнего вида документации.
- Stoplight и другие коммерческие платформы предоставляют более продвинутые возможности для создания, хранения и публикации документации с интеграцией CI/CD и возможностями для совместной работы.
Публикация документации может происходить как на внутренних серверах компании, так и на общедоступных ресурсах. Важно обеспечить легкий доступ к актуальной документации для всех заинтересованных сторон, включая разработчиков, тестировщиков и внешних пользователей API.
Самостоятельная работа
У проекта code-basics тоже есть свой API. В репозитории по ссылке находится его OpenAPI спецификация в yaml формате.
- Откройте спецификацию и изучите ее. Посмотрите, какие элементы в ней есть. Эта спецификация сгенерирована на основании существующего кода
- Скачайте файл спецификации себе, он понадобится нам для работы
Спецификация это конечно хорошо. Но чтобы другим людям было проще использовать наш API, нужно получить документацию в удобном человекочитаемом виде. Для этого существуют специальные сервисы. Swagger UI позволяет получить подробную и интерактивную документацию в браузере исходя из спецификации. В ней можно не только посмотреть доступные эндпоинты, но и выполнить к ним запрос и получить ответ.
- Откройте редактор и загрузите туда спецификацию. Изучите сгенерированную документацию
- Попробуйте выполнить несколько запросов к эндпоинтам
Дополнительные материалы
Остались вопросы? Задайте их в разделе «Обсуждение»
Вам ответят команда поддержки Хекслета или другие студенты
Для полного доступа к курсу нужен базовый план
Базовый план откроет полный доступ ко всем курсам, упражнениям и урокам Хекслета, проектам и пожизненный доступ к теории пройденных уроков. Подписку можно отменить в любой момент.
