Nswag как быстро сгенерировать код по swagger файлу

Обновлено: 24.01.2025

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

Ручное формирование документации — утомительное занятие. Поэтому разработчики придумали Swagger. С его помощью на основе кода можно автоматически сгенерировать спецификации API.

Что такое Swagger?

В 2015 году проект Swagger сделали открытым и передали OpenAPI Initiative. Теперь сама спецификация называется OpenAPI. Swagger — инструментарий для работы с OpenAPI, название которого используется в коммерческих и некоммерческих продуктах. Если кто-то называет саму спецификацию Swagger, то это не совсем верно.

Документ спецификации OpenAPI использует YAML, но также может быть написан в формате JSON. Сам по себе он является объектом JSON.

Основные подходы

Swagger предлагает два основных подхода к генерированию документации:

• Автогенерация на основе кода.
• Самостоятельная разметка-написание.

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

Чтобы пользоваться вторым подходом, нужно знать синтаксис Swagger. Описания можно готовить в формате YAML/JSON. Можно упростить эту задачу, используя Swagger Editor. Конечно, второй подход позволяет сделать документацию более качественной и кастомной для каждого конкретного проекта и его особенностей, к тому же все не так сложно как может показаться, это потребует минимальных дополнительных усилий.

Swagger Core

Это Java-реализация спецификации. Для ее использования потребуется:

• Java 8 и выше
• Apache Maven 3.0.4 и выше
• Jackson 2.4.5 и выше

Для его внедрения в проект используются две зависимости. Вот примеры:

Другой способ — настроить maven-плагин. Тогда описания при сборке проекта будут генерироваться в файл YAML. Пример:

Для конфигурации нужны еще два бина (beans). В них мы описываем название приложения, версию API, добавляем другие важные данные. Посмотреть примеры можно в этом репозитории на GitHub . В нем представлены образцы Swagger Core из библиотеки Java. Каждый образец содержит файл Readme , в котором подробно описано, как его запускать и что проверять.

После настройки конфигурации мы получим аннотации, которые можно использовать для документирования кода.

Аннотация	Использование
@Operation	Для описания операции или метода HTTP
@Parameter	Для представления одного параметра в операции
@RequestBody	Для представления тела запроса в операции
@ApiResponse	Для представления тела ответа в операции
@Tag	Для представления тегов операции или определения OpenAPI
@Server	Для представления серверов операции или определения OpenAPI
@Callback	Для описания набора запросов
@Link	Для представления ссылки времени разработки для ответа
@Schema	Для определения входных и выходных данных
@ArraySchema	Для определения входных и выходных данных для типов массивов
@Content	Для представления схемы и примеров для мультимедиа
@Hidden	Для скрытия ресурса, операции или свойства

Swagger Codegen

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

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

Плюсы Swagger Codegen:

• Генерирование серверов — позволяет избавиться от рутины, создавая шаблонный код на 20+ языках.
• Упрощенное генерирование SDK — можно создавать клиентские наборы на 40+ языках для быстрой интеграции с вашим API.
• Постоянное обновление инструментов.

Чтобы добавить Swagger Codegen в проект, используйте зависимость:

Как и в случае с Swagger Core, можно настроить maven-плагин для генерации клиента или мок-сервера.

Swagger Codegen предоставляет следующие команды:

• Config-help — помощь с настройкой выбранного языка.
• Generate — генерирование кода с выбранным генератором.
• Help — вывод справочной информации про openapi-generator .
• List — список доступных генераторов.
• Meta — генератор набора шаблонов и настроек Codegen. Использует информацию о выбранном языке.
• Validate — проверка спецификации.
• Version — отображение используемой версии.

Самые полезные команды — generate и validate . Первая позволяет создать клиент, а вторая — проверить его соответствие спецификации. Посмотреть полный список возможностей можно с помощью команды help после запуска jar-файла.

Swagger UI

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

Плюсы Swagger UI:

• Нет зависимостей. Интерфейс доступен в любой среде разработки.
• Полная поддержка браузерами.
• Удобное взаимодействие для других разработчиков и клиентов. Можно проверить все операции, предоставляемые API, даже не имея специальных знаний.
• Простая навигация. Ресурсы и конечные точки представлены в виде аккуратно распределенного на категории списка.
• Можно настраивать стиль и пользовательский интерфейс так, как вам хочется.

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

Swagger Editor

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

Плюсы Swagger Editor:

• Работает в любой среде разработки, локально и в сети.
• Дает обратную связь — показывает ошибки в синтаксисе по мере написания, проверяя его на соответствие OpenAPI.
• Позволяет мгновенно визуализировать API через Swagger UI.
• Помогает писать документацию быстрее благодаря интеллектуальному автозаполнению.
• Предоставляет гибкие инструменты для настройки конфигурации — от темы оформления до межстрочного интервала.
• Предлагает создание серверных заглушек и клиентских библиотек для вашего API на всех популярных языках.

Верхний уровень спецификации OpenAPI 3.0 содержит восемь объектов. Внутри этих верхнеуровневых объектов есть много вложенных объектов. Давайте далее последовательно рассмотрим все объекты верхнего уровня.

Первое и самое важное свойство в документации. Объект содержит информацию о спецификации OpenAPI. Пример:

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

Объект содержит базовый путь, который используется в запросах через API. Под базовым путём понимается часть адреса, которая находится перед конечной точкой. Servers можно гибко настраивать, например, указывая несколько адресов для тестирования:

Спецификация OpenAPI определяет path как объект для указания конечной точки. Каждый path содержит вложенный объект operations — методы GET, POST, PUT, DELETE . Например:

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

Теперь можно ссылаться на эту схему и при необходимости без проблем дополнять её новыми полями.

Объект для объявления того, какие механизмы безопасности можно использовать в API.

Например, требование безопасности OAuth2 :

Объект добавляет метаданные к тегу, который используется объектом operations . Например:

В этом объекте можно указать дополнительную информацию. Например:

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

Использование Petstore для знакомства

Авторизация

Прежде всего нужно авторизоваться. Для этого нажмите на кнопку Authorize и заполните необходимую информацию.

В примере используется модель авторизации OAuth 2.0. На самом деле, код представлен в демонстрационных целях, никакой реальной логики за авторизацией нет. Так что можно просто закрыть окно.

Создание запроса

Создадим первый запрос к API. Для этого:

1. Разверните конечную точку POST/pet .
2. Нажмите на кнопку Try it out . После этого тело запроса станет редактируемым.
3. Найдите поле Example Value и измените id на случайное число.
4. Измените name на любое имя.
5. Нажмите Execute для выполнения запроса.

Система отправит запрос и покажет curl . Вы можете выбрать, в каком формате отобразить ответ — XML или JSON.

Проверка результата

Напоследок выполним ещё один запрос, чтобы убедиться, что питомец создан.

1. Разверните конечную точку GET/pet/ .
2. Нажмите на кнопку Try it out , чтобы сделать тело запроса редактируемым.
3. Введите id питомца, который вы указали ранее в запросе POST .
4. Нажмите Execute , чтобы выполнить запрос.

В ответе должно отобразиться имя созданного ранее питомца.

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

Как выглядят сайты с документацией Swagger UI

Вот ещё несколько примеров реализации Swagger:

— описание API онлайн-магазина музыкальных инструментов. — описание API базы данных фильмов и ТВ-шоу.

Обращает на себя внимание краткость документации, реализованной с помощью Swagger. Это объясняется тем, что сам по себе Swagger UI предназначен для интерактивного взаимодействия. Нет смысла читать пространные описания, когда можно просто выполнять указанные запросы и проверять, какие ответы приходят.

Как встроить Swagger UI в существующий сайт

При использовании Swagger UI необязательно использовать автономный сайт по типу Petstore . Можно встраивать Swagger в существующую страницу. Вот пример такой страницы:

Здесь встроен экземпляр Swagger UI, который показывает файл OpenAPI для OpenWeatherMapAPI . Выглядит как неплохо сверстанная документация, хотя в оформлении остались дефолтные элементы. При большом желании их тоже можно поменять. Гораздо важнее, что можно автоматизировать процесс обновления такой внешней документации.

Чтобы встроить Swagger UI на свой сайт:

Отображение документации можно проверить локально. Если всё в порядке, загрузите папку dist (ее можно переименовать) на сервер и добавьте документацию на существующий сайт.

Подробную инструкцию можно найти на этой странице на GitHub .

Заключение

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

Чтобы разобраться со Swagger дополнительно, посмотрите эти видео.

Например, вот доклад технического писателя из «Яндекса» о том, что такое вообще API и как работать со Swagger. Много времени также уделено практической части — в ней делается простой Swagger, который затем отображается в Swagger UI и в документации.

Ещё одно классное видео — подробное объяснение, как использовать Swagger:

Highload нужны авторы технических текстов. Вы наш человек, если разбираетесь в разработке, знаете языки программирования и умеете просто писать о сложном!
Откликнуться на вакансию можно здесь .

Публичные контракты, спецификации – публичные интерфейсы, через которые можно взаимодействовать с сервисом. В тексте означают одно и то же.

О чем статья

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

Грамотное использование описанных ниже техник и инструментов позволит быстрее выкатывать новые фичи и не ломать старые.

Как выглядит проблема

Есть система, которая состоит из нескольких сервисов. Эти сервисы закреплены за разными командами.

Сервисы-потребители зависят от сервиса-поставщика.
Система развивается, и однажды сервис-поставщик меняет свои публичные контракты.

Если сервисы-потребители не готовы к изменениям, то система перестает полноценно работать.

Как решить эту проблему

Команда сервиса поставщика сама всё поправит

Так можно поступить, если команда поставщика владеет предметной областью других сервисов и имеет доступ к их git-репозиториям. Это сработает только в небольших проектах, когда зависимых сервисов немного. Это самый дешевый вариант. По возможности, следует воспользоваться им.

Актуализировать код своего сервиса команде потребителя

Почему ломают другие, а чиним мы?

Однако главный вопрос — это как починить свой сервис, как теперь выглядит контракт? Нужно изучать новый код сервиса поставщика или обращаться к их команде. Тратим время на изучение кода и на взаимодействие с другой командой.

Подумать, что сделать чтобы проблема не проявлялась

Самый разумный вариант в долгосрочной перспективе. Рассмотрим его в следующем разделе.

Как не допустить проявления проблемы

Жизненный цикл разработки ПО можно представить тремя этапами: проектирование, реализация и тестирование.

Каждый из этапов нужно расширить следующим образом:

1. На этапе проектирования декларативно определяем контракты.
2. Во время реализации генерируем серверный и клиентский код по контрактам.
3. При тестировании проверяем контракты и стараемся учитывать потребности клиентов (CDC).

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

Так выглядит наша экосистема.
Кружочки – сервисы, а стрелочки – каналы общения между ними.

Frontend – клиентское web-приложение.

Большинство стрелок ведут в Storage Service. В нем хранятся документы. Это самый важный сервис. Ведь наш продукт – это система электронного документооборота.

Стоит этому сервису поменять свои контракты, система сразу перестанет работать.

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

Хочется уйти от ручной актуализации в сторону автоматической. Это поможет увеличить скорость изменения клиентского кода и сократить количество ошибок. Под ошибками понимаются опечатки в URL, ошибки из-за невнимательности и т.п.

Однако, этим подходом не исправишь ошибки в клиентской бизнес-логике. Скорректировать её можно только вручную.

От проблемы к задаче

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

Вопросы

В ходе решения задачи встали вопросы:

• какой инструмент выбрать;
• как получить контракты;
• где расположить контракты;
• где расположить код клиента;
• в какой момент выполнять генерацию.

Какой инструмент выбрать

Инструменты для работы с контрактами представлены по двум направлениям – RPC и REST.

Отличия в вызове RPC и REST представлены здесь

Инструменты

В таблице представлено сравнение инструментов для работы с REST и RPC.

Свойства	OpenAPI	WSDL	Thrift	gRPC
Тип	REST		RPC
Платформа	Не зависит
Язык	Не зависит
Последовательность разработки*	code first, spec first	code first, spec first	spec first	code first, spec first
Транспортный протокол	HTTP/1.1	любой (REST требует HTTP)	собственный	HTTP/2
Вид	спецификация		фреймворк
Комментарий	Низкий порог вхождения, много документации	Избыточность XML, тянет за собой SOAP и т.п.	Высокий порог вхождения, мало документации	Средний порог вхождения, лучше документация

Code first — сначала пишем серверную часть, а затем по ней получаем контракты. Удобно, когда серверная часть уже написана. Не нужно вручную описывать контракты.

Spec first — сначала определяем контракты, потом по ним получаем клиентскую часть и серверную часть. Удобно в начале разработки, когда кода еще нет.

WSDL не подходит из-за своей избыточности.

Apache Thrift слишком экзотический и непростой в освоении.

OpenAPI не требует дополнительных обновлений. Подкупает обилие инструментов, поддерживающих работу с REST и этой спецификацией. Выбираем его.

Инструменты для работы с OpenAPI

В таблице представлено сравнение инструментов для работы с OpenAPI.

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

OpenApiTools интересный инструмент с кучей настроек, но он не поддерживает code first. Его преимущество – это способность генерировать серверный код на множестве языков.

Где расположить контракты. Как осуществить доступ сервисов к контрактам

Здесь представлены решения по организации хранения контрактов. Решения перечислены в порядке увеличения их сложности.

• папка проекта сервиса поставщика – самый простой вариант. Если нужно обкатать подход, то выбрать его.
• общая папка – допустимый вариант, если нужные проекты находятся в одном репозитории. В долгосрочной перспективе будет сложно поддерживать целостность контрактов в папке. Для этого может потребоваться дополнительный инструмент, чтобы учитывать разные версии контрактов и т.п.
• отдельный репозиторий для спецификаций – если проекты находятся в разных репозиториях, то контракты следует вынести в общедоступное место. Недостатки такие же, как и общей папки.
• через API сервиса (swagger.ui, swaggerhub) – отдельный сервис, который занимается управлением спецификациями.

В какой момент выполнять генерацию

Теперь нужно определиться, в какой момент выполнять генерацию кода.
Если бы контракты располагались в общем доступе, сервисы-потребители могли бы получать контракты и сами генерировать код по необходимости.

Мы решили расположить контракты в папке с проектом сервиса-поставщика. Значит, генерацию можно сделать после сборки самого проекта сервиса поставщика.

Где расположить код клиента

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

Преимущества этого решения:

• клиентский код близко к своему сервису и постоянно в актуальном состоянии;
• потребители могут использовать ссылку на проект в рамках одного репозитория.

• не сработает, если потребуется сгенерировать клиента в другой части системы, Например, другой репозиторий. Решается использованием, как минимум, общей папки для контрактов;
• потребители должны быть написаны на том же языке. Если нужен клиент на другом языке, нужно использовать OpenApiTools.

Прикручиваем NSwag

Атрибуты контроллеров

Нужно подсказать NSwag, как сгенерировать правильную спецификацию по нашим контроллерам.

Для этого необходимо расставить атрибуты.

Процессор для генерации спецификации для файловых операций

Идея заключается в том, что можно написать свой атрибут и процессор для обработки этого атрибута.

Вешаем атрибут на контроллер, и, когда NSwag встретит его, он обработает его с использованием нашего процессора.

Чтобы это реализовать, NSwag предоставляет классы OpenApiOperationProcessorAttribute и IOperationProcessor.

В нашем проекте мы сделали своих наследников:

• FileUploadOperationAttribute: OpenApiOperationProcessorAttribute
• FileUploadOperationProcessor: IOperationProcessor

Конфигурация NSwag для генерации спецификации и кода

В конфиге 3 основные секции:

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

Генерируем спецификацию и клиентский код при сборке проекта сервиса-поставщика

Чтобы после сборки проекта сервиса-поставщика генерировалась спецификация и код, сделали следующее:

1. Создали WebApi проект для клиента.
2. Написали конфиг для Nswag CLI – Nswag.json (описан в предыдущем разделе).
3. Написали PostBuild Target внутри csproj проекта сервиса поставщика.

Вывод

Мы выбрали вариант с OpenAPI, т.к. внедрить его несложно, а инструменты для работы с этой спецификацией весьма развиты.

Выводы по OpenAPI и GRPC:

• спецификация многословна;
• генерация прикручивается быстро за счёт хорошей документации к спецификации и инструментам, её реализующим;
• пришлось докрутить процессор для генерации спецификации;
• много атрибутов на контроллерах отвлекают.

Затем на основе полученной спецификации реализовали генерацию клиентского кода. Теперь нам не нужно вручную актуализировать клиентский код.

Были проведены исследования в области версионирования и тестирования контрактов. Однако не удалось опробовать все это дело на практике из-за нехватки ресурсов.

Версионирование публичных контрактов

Зачем нужно версионирование публичных контрактов

После изменений в сервисах-поставщиках вся система должна оставаться в согласованном, рабочем состоянии.

Нужно избежать breaking changes в публичном API, чтобы не поломать клиентов.

Варианты решения

Без версионирования публичных контрактов

Команда сервиса-поставщика сама исправляет сервисы-потребители.

Этот подход не сработает, если у команды сервиса-поставщика нет доступа к репозиториям сервисов-потребителей или не хватает компетенций. Если таких проблем нет, то можно обойтись без версионирования.

Использовать версионирование публичных контрактов

Команда сервиса-поставщика оставляет предыдущую версию контрактов.

Данный подход лишен недостатков предыдущего, но добавляет другие сложности.
Нужно определиться со следующим:

• какой инструмент использовать;
• когда вводить новую версию;
• как долго поддерживать старые версии.

Какой инструмент использовать

В таблице представлены возможности OpeanAPI и GRPC, связанные с версионированием.

Deprecated – значит, что этим API больше не стоит пользоваться.

Оба инструмента поддерживают атрибуты версии и Deprecated.

Если использовать OpenAPI и подход code first, снова нужно писать процессоры для создания правильной спецификации.

Когда вводить новую версию

Новую версию нужно вводить, когда изменения в контрактах не сохраняют обратную совместимость.

Как проверить, что изменения нарушают совместимость между новой и старой версией контрактов?

Как долго поддерживать версии

На этот вопрос нет правильного ответа.

Чтобы убрать поддержку старой версии, нужно знать, кто пользуется вашим сервисом.

Будет плохо, если версию уберут, а ею ещё кто-то пользуется. Особенно сложно, если вы не контролируете своих клиентов.

Так что можно сделать в этой ситуации?

• уведомлять клиентов, что старая версия больше поддерживаться не будет. В этом случае можем потерять доход клиентов;
• поддерживать весь набор версий. Растет стоимость поддержки ПО;
• чтобы ответить на этот вопрос, нужно спросить бизнес – превышает ли доход от старых клиентов затраты на поддержку старых версий ПО? Может выгоднее попросить клиентов обновиться?

Если публичные контракты используются в замкнутой системе, можно воспользоваться подходом CDC. Так можем узнавать о том, когда клиенты перестали использовать старые версии ПО. После этого можно убирать поддержку старой версии.

Вывод

Используйте версионирование, только если без него не обойтись. Если решили использовать версионирование, то при проектировании контрактов учитывайте совместимость версий. Нужно найти баланс между стоимостью поддержки старых версий и выгодой, которую она дает. Также стоит определиться с тем, когда можно перестать поддерживать старую версию.

Тестирование контрактов и CDC

Данный раздел освещается поверхностно, т.к. нет серьезных предпосылок для внедрения этого подхода.

Consumer driven contracts (CDC)

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

1. Потребитель описывает контракт.
2. Поставщик реализует этот контракт у себя.
3. Этот контракт используется в CI-процессе у потребителя и поставщика. Если процесс нарушился, значит кто-то перестал соблюдать контракт.

PACT – это инструмент, который реализует эту идею.

1. Потребитель пишет тесты с помощью PACT библиотеки.
2. Эти тесты преобразуются в артефакт – pact-файл. Он содержит информацию о контрактах.
3. Поставщик и потребитель используют pact-файл для запуска тестов.

Полезные ссылки про Pact

• Pact broker – решение для управления pact-файлами docs.pact.io/pact_broker
• Pact пока не поддерживает GRPC. Подробнее про roadmap Pact pact.canny.io.
• Подробнее про PACT на docs.pact.io.
• Почему стоит использовать PACT docs.pact.io/faq/convinceme

Как CDC можно встроить в CI

• самостоятельно развернув Pact + Pact broker;
• приобрести готовое решение Pact Flow SaaS.

Вывод

Pact нужен для обеспечения соответствия контрактов. Он покажет, когда изменения контрактов нарушают ожидания сервисов-потребителей.

Этот инструмент годится, когда поставщик подстраивается под заказчика – клиента. Такое возможно только внутри изолированной системы.

Если вы делаете сервис для внешнего мира и не знаете кто ваши клиенты, то Pact не для вас.

Резюме

Отдельные на переднем и заднем концах, В эпоху, когда Restful API был популярен, идеальная документация по интерфейсу стала средством коммуникации. Введено в проект Swagger (также известный как OpenAPI) - хороший выбор, поскольку он позволяет визуализировать данные интерфейса. Будет продемонстрировано ниже

Как использовать Nswag для создания документов API

Как использовать NSwagStudio для генерации клиентского кода и его тестирования

Что такое Swagger / OpenAPI?

Swagger - это не зависящая от языка спецификация для описания REST API. Проект Swagger был подарен проекту OpenAPI, и теперь он называется Open API. Эти два имени могут использоваться как взаимозаменяемые, но предпочтительнее OpenAPI. Это позволяет компьютерам и персоналу понимать функции службы без прямого доступа к реализации (исходный код, доступ к сети, документация). Одна из целей - минимизировать объем работы, необходимой для подключения и отключения сервисов. Другая цель - сократить время, необходимое для точной записи услуг.

Nswag VS Swashbuckle？

1. Используйте Nswag для создания документов API.

Элемент конфигурации

Запустить проект

Установите пакет nuget NSwag.AspNetCore

Затем настройте службу Nswag и промежуточное ПО в файле Startup.cs.

Добавить службу в методе ConfigureServices

Добавьте промежуточное ПО Nswag в методе Configure

Элемент конфигурации

Запустить проект

два, Как использовать NSwagStudio для генерации клиентского кода и его тестирования

Предоставление графического интерфейса - основная функция NSwag. Вам нужно только загрузить и установить NSwagStudio для генерации клиентского кода.

Установите NSwagStudio сейчас

Конфигурация NSwagStudio, генерация клиентского кода

Создать тестовый клиентский проект

Скачайте и установите NSwagStudio

Конфигурация NSwagStudio, генерация клиентского кода

Пока что клиентский код генерируется автоматически.

Просмотреть часть сгенерированного кода

Создать тестовый клиентский проект

Создайте проект управляющей программы и назовите его " WebApiClient ”。

Добавьте автоматически сгенерированный класс WeatherForecastClient в клиентский проект, а затем установите Newtonsoft.

Наконец, добавьте тестовый код в функцию Main и начните использовать Api.

Запустите клиентское приложение и вызовите api

Конечно, если вам нужно отлаживать внутренний код проекта api, вы можете установить точки останова и ввести пошаговую отладку

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

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

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

Создание документации вручную - утомительный процесс. Swagger поможет вам упростить эту работу.

Что такое Swagger?

Swagger автоматически генерирует спецификацию вашего API в виде json. А проект Springdoc создаст удобный UI для визуализации. Вы не только сможете просматривать документацию, но и отправлять запросы, и получать ответы.

Также возможно сгенерировать непосредственно клиента или сервер по спецификации API Swagger, для этого нужен генератор кода Swagger-Codegen.

Swagger использует декларативный подход, все как мы любим. Размечаете аннотациями методы, параметры, DTO.

Вы найдете все примеры представленные тут в моем репозитории.

Создание REST API

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

Добавим примитивные контроллеры и одно DTO. Суть нашей системы – программа лояльности пользователей.

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

В качестве DTO у нас будет класс UserDto – это пользователь нашей системы. У него пять полей, из которых 3 обязательны:

• имя
• уникальный ключ
• пол пользователя
• количество баллов
• дата регистрации

Для взаимодействия с нашей бизнес-логикой, добавим три контроллера: UserController , PointContoller , SecretContoller .

UserController отвечает за добавление, обновление и получение пользователей.

PointContoller отвечает за взаимодействие с баллами пользователя. Один метод этого контроллера отвечает за добавление и удаление балов пользователям.

Метод destroy в SecretContoller может удалить всех пользователей.

Настраиваем Swagger

Теперь добавим Swagger в наш проект. Для этого добавьте следующие зависимости в проект.

Для каждого метода доступные следующие данные: статус ответа, тип содержимого и список параметров.

Поэтому после добавления зависимостей, у нас уже есть документация. Чтобы убедиться в этом, переходим по адресу: localhost:8080/swagger-ui.html

Swagger запущенный с дефолтными настройками

Также можно вызвать каждый метод с помощью пользовательского интерфейса. Откроем метод добавления пользователей.

Пока у нас не очень информативная документация. Давайте исправим это.

Для начала создадим класс конфигурации сваггера SwaggerConfig - имя произвольное.

• title – это название вашего приложения
• version – версия вашего API

Эти данные больше для визуальной красоты UI документации.

Добавление авторов

Добавьте разработчиков API, чтобы было понятно, кто в ответе за это безобразие 😄

Разметка контроллеров

Переопределим описания контроллеров, чтобы сделать документацию понятнее. Для этого пометим контроллеры аннотацией @Tag .

Скрыть контроллер

У нас есть контроллер, который мы хотим скрыть – SecretController . Аннотация @Hidden поможет нам в этом.

Аннотация скрывает контроллер только из Swagger. Он все также доступен для вызова. Используйте другие методы для защиты вашего API.

Наша документация стала намного понятнее, но давайте добавим описания для каждого метода контроллера.

Разметка методов

Аннотация @Operation описывает возможности методов контроллера. Достаточно определить следующие значения:

Разметка переменных метода

При помощи аннотации Parameter также опишем переменные в методе, который отвечает за управление баллами пользователей.

С помощью параметра required можно задать обязательные поля для запроса. По умолчанию все поля необязательные.

Разметка DTO

Разработчики стараются называть переменные в классе понятными именами, но не всегда это помогает. Вы можете дать человеко-понятное описание самой DTO и ее переменным с помощью аннотации @Schema .

Сваггер заполнит переменные, формат которых он понимает: enum, даты. Но если некоторые поля DTO имеют специфичный формат, то помогите разработчикам добавив пример.

Выглядеть это будет так:

Но подождите, зачем мы передаем дату регистрации. Да и уникальный ключ чаще всего будет задаваться сервером. Скроем эти поля из swagger с помощью параметра Schema.AccessMode.READ_ONLY :

Валидация

Добавим валидацию в метод управления баллами пользователя в PointController . Мы не хотим, чтобы можно было передать отрицательные баллы.

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

Давайте посмотрим на изменения спецификации.

Для поля point появилось замечание minimum: 0 .

И все это нам не стоило ни малейшего дополнительного усилия.

Этих аннотаций вам хватит, чтобы сделать хорошее описание API вашего проекта.

Если нужны более тонкие настройки, то вы без труда сможете разобраться открыв документацию к аннотациям сваггера.

Читайте также:

  
• Файл не существует но существует
  
• Sqlldr oracle как установить
  
• Как сделать смарт тв из компьютера
  
• Сколько частей игры tomb raider на xbox 360
  
• Что делать если взломали скайп