Кратко про OpenAPI и Swagger

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

Определено все остальное: Архитектурный стиль и ограничения REST, предложенный Роем Филдингом в 2000 году, представляет собой архитектурный стиль взаимодействия в распределенных системах. Его шестью ограничениями являются разделение клиент–сервер, запросы без сохранения состояния, возможность кэширования, единый интерфейс, многоуровневая система и возможность использования кода по требованию. Эти ограничения обеспечивают независимую эволюцию клиентов и серверов и упрощают масштабируемость. Единообразие также определяет, что отправляется, куда и в каком формате.

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

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

Языки описания API как контракт Язык описания API представляет собой интерфейс в форме, понятной как людям, так и машинам. Люди просматривают спецификацию, чтобы понять возможности, входные данные, выходные данные и ошибки, не углубляясь в код. Машины создают серверы и клиенты на основе спецификации или выводят спецификацию из существующих реализаций. Распространенные опции включают WSDL, API Blueprint и семейство OpenAPI.

OpenAPI - это спецификация, не зависящая от языка OpenAPI - это спецификация интерфейса, не зависящая от языка, которая раскрывает возможности и требования сервиса без разбора кода по полочкам. Она удобочитаема как для пользователя, так и для машины и обеспечивает согласованные контракты в разных стеках. Последняя версия, на которую здесь ссылаются, - 3.1.0 (февраль 2021 г.), в то время как история разработки восходит к 2011 году. Важно отметить, что спецификация отличается от любого конкретного языка программирования.

От истоков Swagger до инициативы OpenAPI Swagger был создан в 2011 году как внутренняя разработка команды разработчиков онлайн-словаря английского языка и был выпущен под разрешительной лицензией. Внедрение Swagger известными компаниями, включая Google и Microsoft, ускорило его рост. В 2015 году была сформирована инициатива OpenAPI, а 1 января 2016 года спецификация Swagger была переименована в OpenAPI. Все, что было до версии 3.0, называлось Swagger (как спецификация, так и программное обеспечение), а после версии 3.0 спецификация стала OpenAPI. Swagger остается названием инструментария, связанного со спецификацией.

Подходы "Сначала дизайн" и "Сначала код" Сначала проектируется интерфейс, а затем выполняется кодирование, чтобы команды могли создавать сервер и клиентские приложения параллельно. Это снижает общие затраты за счет заблаговременного продумывания поведения и безопасности и позволяет разработчикам получать удовольствие от четких и согласованных контрактов. Code-first помечает код тегами для автоматической генерации спецификации, что ускоряет запуск и позволяет избежать предварительной работы по проектированию. Однако code-first плохо масштабируется для больших API из-за помехи в аннотациях и накладных расходов на обслуживание. Время вывода на рынок - это компромисс: разработка в первую очередь обеспечивает более высокое качество, в то время как разработка кода в первую очередь способствует более быстрому первоначальному запуску.

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

Создание OpenAPI вручную: анатомия YAML/JSON При ручном создании OpenAPI используется YAML или JSON со строгим описанием. В метаданных указывается версия спецификации (openapi 3.0/3.1 или swagger 2), а также информация и лицензия. Серверы содержат список внутренних URL-адресов; пути определяют операции, ответы и поведение, например, конечная точка возвращает всех животных с 200 и 404 результатами. Типы носителей, такие как application/json, указывают на схемы в разделе components/schemas, например, Pet с именем и типом. В параметрах и текстах запросов указываются требуемые флаги, типы и форматы, а модели предоставляются встроенно или по ссылке.

Практические Рекомендации По Проектированию REST, Встроенные в Спецификацию Предпочитайте JSON для полезной нагрузки, чтобы упростить взаимодействие. Используйте существительные, а не глаголы, и расширяйте коллекции; моделируйте вложенность естественным образом, например, articles/{id}/comments. Возвращайте соответствующие коды состояния HTTP вместо пользовательской семантики. Поддерживайте фильтрацию, сортировку и разбиение на страницы в явном виде. Заранее разработайте систему безопасности и обновите свой API, чтобы старые и новые клиенты могли работать параллельно.

Инструменты: Swagger Suite, клиенты, макетирование и тестирование Swagger Editor позволяет создавать и редактировать спецификации с возможностью предварительного просмотра в реальном времени, Swagger UI отображает интерактивную документацию, а Codegen создает серверный и клиентский код на многих языках, таких как Java, JavaScript, Python и Go. Postman и Insomnia импортируют OpenAPI, генерируют коллекции запросов и отправляют вызовы, при этом Insomnia также редактирует спецификацию встроенным способом. Макетный сервер может импортировать спецификацию, генерировать заглушки конечных точек и принимать тестовые запросы; если указать клиенту на него, он вернет запрошенные ответы, которые вы можете проверить в браузере. Автоматизированные инструменты проверки соответствия запускают тесты, чтобы проверить, соответствует ли реальный сервер описанию в OpenAPI, а в рекомендуемых докладах демонстрируются более подробные макеты серверов и методы документирования. Основные вопросы и ответы: существуют конвертеры между версиями спецификаций, которые поддерживаются, многие государственные и корпоративные системы по‑прежнему полагаются на SOAP/ XSD и очереди, а API‑first рассматривает интерфейс как основной продукт, в то время как design-first фокусируется на моделировании перед внедрением.