Swashbuckle.AspNetCore
v7.0.0
| Важное уведомление, если вы обновляете между основными версиями! |
|---|
| * Если вы обновляетесь с 4.x до 5.x, есть несколько нарушающих изменений, о которых можно знать. Для получения подробной информации см. Примечания по выпуску * Если вы сначала совершаете прыжок с 3.x до 4.x, там тоже будут драконы. Смотрите эти заметки о выпуске здесь |
Swagger Tooling for API, построенные с Core ASP.NET. Создайте красивую документацию API, включая пользовательский интерфейс для изучения и тестирования, непосредственно с ваших маршрутов, контроллеров и моделей.
В дополнение к своему генератору Swagger 2.0 и OpenAPI 3.0, Swashbuckle также предоставляет встроенную версию The Awesome Swagger-UI, которая оснащена генерируемым Swagger Json. Это означает, что вы можете дополнить свой API с живой документацией, которая всегда синхронизируется с последним кодом. Лучше всего, это требует минимального кодирования и технического обслуживания, что позволяет вам сосредоточиться на создании потрясающего API.
И это еще не все ...
После того, как у вас есть API, который может описать себя в Swagger, вы открыли сундук с сокровищницами инструментов на основе Swagger, включая генератор клиентов, который может быть нацелен на широкий спектр популярных платформ. Смотрите Swagger-Codegen для более подробной информации.
| Версия Swashbuckle | ASP.NET CORE | Swagger / Openapi Spec. | Swagger-Ui | Redoc UI |
|---|---|---|---|---|
| CI | > = 2,0,0 | 2.0, 3.0 | 5.xx | 2.xx |
| 6.9.0 | > = 2,0,0 | 2.0, 3.0 | 5.17.14 | 2.1.5 |
| 5.6.3 | > = 2,0,0 | 2.0, 3.0 | 3.32.5 | 2.0.0-RC.40 |
| 4.0.0 | > = 2,0,0, <3.0.0 | 2.0 | 3.19.5 | 1.22.2 |
| 3.0.0 | > = 1,0,4, <3.0.0 | 2.0 | 3.17.1 | 1.20.0 |
| 2.5.0 | > = 1,0,4, <3.0.0 | 2.0 | 3.16.0 | 1.20.0 |
Установите стандартный пакет Nuget в свое приложение ASP.NET Core.
Package Manager : Install-Package Swashbuckle.AspNetCore CLI : dotnet add package Swashbuckle.AspNetCore
В методе ConfigureServices of Startup.cs зарегистрируйте генератор Swagger, определяя один или несколько документов Swagger.
Использование microsoft.openapi.models;
services.addmvc (); services.addswaggergen (c => {c.swaggerdoc ("v1", new openapiinfo {title = "my api", version = "v1"});});Убедитесь, что ваши действия и параметры API украшены явными «HTTP» и «из» привязки.
[Httppost] public void createProduct ([от продукта из тела] продукта) ...
[Httpget] public ienumerable <Продукт> SearchProducts ([ormquery] String Keywords) ...
ПРИМЕЧАНИЕ. Если вы опустите явные привязки параметров, генератор будет описать их как параметры «запроса» по умолчанию.
В методе Configure вы должны выставить сгенерированный чванство как конечную точку (ы) JSON по одному из следующих методов:
app.mapendpoints (endpoints => {// ... endpoints.mapswagger ();});app.useswagger ();
На этом этапе вы можете раскрутить свое приложение и просмотреть сгенерированный Swagger json в "/swager/v1/swagger.json".
Вставьте промежуточное программное обеспечение
Добавьте конечные точки, если вы используете маршрутизацию на основе конечных точек.
При желании вставьте промежуточное программное обеспечение Swagger-UI, если вы хотите разоблачить интерактивную документацию, указав конец (ы) Swagger JSON для его питания.
app.useswaggerui (c => {c.swaggerendpoint ("v1/swagger.json", "my api v1");});Теперь вы можете перезапустить свою заявку и проверить автоматические интерактивные документы в "/swagger".
В версиях до 5.0.0 Swashbuckle будет генерировать схемы (описания типов данных, выявленных API) на основе поведения Newtonsoft Serializer. Это имело смысл, потому что это был сериализатор, который в то время поставлялся с ядром ASP.NET. Однако, поскольку версия 3.0.0 , ASP.NET Core представляет новую систему сериализатора. Образец. От Swashbuckle 5.0.0 и за пределами аналогичной схемы используется. То есть, нестандартный Swashbuckle, вы предполагаете, что вы используете сериализатор STJ и генерируете схемы, основанные на его поведении. Если вы используете Newtonsoft , вам нужно будет установить отдельный пакет Swashbuckle и явно зарегистрировать. Это требуемый шаг, независимо от того, какую версию ядра ASP.NET вы используете .
В итоге ...
Если вы используете System.text.json (STJ) , то настройка, описанная выше, будет достаточной, а параметры/атрибуты STJ будут автоматически удостоены генератора Swagger.
Если вы используете Newtonsoft , вам нужно установить отдельный пакет и явно выбрать, чтобы настройки/атрибуты Newtonsoft автоматически удостоены генератора Swagger:
Package Manager : Install-Package Swashbuckle.AspNetCore.Newtonsoft CLI : dotnet add package Swashbuckle.AspNetCore.Newtonsoft
services.addmvc (); services.addswaggergen (c => {c.swaggerdoc ("v1", new openapiinfo {title = "my api", version = "v1"});}); services.addswaggergennewtonsoftsupport (); // Явный Opt -In - нужно размещать после addswaggergen () Swashbuckle в значительной степени зависит от ApiExplorer , слоя метаданных API, который поставляется с ядром ASP.NET. Если вы используете помощник AddMvc для начальной загрузки стека MVC, то ApiexPlorer будет автоматически зарегистрирован, и SB будет работать без проблем. Однако, если вы используете AddMvcCore для более парного стека MVC, вам нужно явно добавить сервис Apiexplorer:
services.addmvccore (). addapiexplorer ();
Кроме того, если вы используете обычную маршрутизацию (в отличие от маршрутизации атрибутов), любые контроллеры и действия на тех контроллерах, которые используют обычную маршрутизацию, не будут представлены в Apiexplorer, что означает, что Swashbuckle не сможет найти эти контроллеры и генерировать Swaggerer операции от них. Например:
app.usemvc (routes => {// swaggergen не найдет контроллеры, которые маршрутизируются с помощью этой методики. routes.maproute ("по умолчанию", "{controller = home}/{action = index}/{id?}") ;});Вы должны использовать маршрутизацию атрибутов для любых контроллеров, которые вы хотите представить в вашем Swagger Document (ы):
[Route («Пример»)] Общедоступный класс.
Обратитесь к документации по маршрутизации для получения дополнительной информации.
Swashbuckle состоит из нескольких компонентов, которые можно использовать вместе или индивидуально в зависимости от ваших потребностей. По своей сути, есть генератор Swagger, промежуточное программное обеспечение, чтобы разоблачить его как конечные точки JSON, и упакованная версия Swagger-UI. Эти 3 пакета могут быть установлены с помощью Swashbuckle.AspNetCore "Metapackage" и будут работать вместе беспрепятственно (см. Начало), чтобы предоставить красивые документы API, которые автоматически генерируются из вашего кода.
Кроме того, есть дополнительные пакеты (инструменты CLI, альтернативный пользовательский интерфейс и т. Д.), Которые вы можете необязательно установить и настраивать по мере необходимости.
| Упаковка | Описание |
|---|---|
| Swashbuckle.aspnetcore.swagger | Разоблачает чванство json конечные точки. Он ожидает, что реализация ISwaggerProvider будет зарегистрирована в контейнере DI, который он запрашивает, чтобы получить OpenAPIDocument(s) , которые затем подвергаются сериализованному JSON |
| Swashbuckle.aspnetcore.swaggergen | Внедряет реализацию ISwaggerProvider , которая может использоваться приведенным выше компонентом. Эта конкретная реализация генерирует OpenApiDocument(s) из ваших маршрутов, контроллеров и моделей |
| Swashbuckle.aspnetcore.swaggerui | Разоблачает встроенную версию Swagger-UI. Вы указываете конечные точки API, где он может получить Swagger JSON, и он использует их для питания интерактивных документов для вашего API |
| Упаковка | Описание |
|---|---|
| Swashbuckle.aspnetcore.annotations | Включает набор пользовательских атрибутов, которые могут быть применены к контроллерам, действиям и моделям для обогащения сгенерированного чванства |
| Swashbuckle.aspnetcore.cli | Предоставляет интерфейс командной строки для извлечения чванства непосредственно из сборки запуска и записать в файл |
| Swashbuckle.aspnetcore.redoc | Разоблачить встроенную версию пользовательского интерфейса Redoc (альтернатива Swagger-UI) |
Эти пакеты предоставляются сообществом с открытым исходным кодом.
| Упаковка | Описание |
|---|---|
| Swashbuckle.aspnetcore.filters | Некоторые полезные фильтры сбоев, которые добавляют дополнительную документацию, например, запросы и ответные примеры, информацию о авторизации и т. Д. См. Его Readme для получения более подробной информации |
| Unchase.swashbuckle.aspnetcore.extensions | Некоторые полезные расширения (фильтры), которые добавляют дополнительную документацию, например, скрыть Pathitems для неприемлемых ролей, исправить перечисления для генерации кода клиента и т. Д. См. Его Readme для получения более подробной информации. |
| Microelements.swashbuckle.fluentvalidation | Используйте правила FluentValidation вместо атрибутов ComponentModel для увеличения схемы чванства. |
| Mmlib.swaggerforocelot | Совокупные документации по микросервисам непосредственно на шлюзе API Ocelot |
Шаги, описанные выше, приведут вас к работе с минимальной настройкой. Тем не менее, Swashbuckle предлагает большую гибкость для настройки по мере того, как вы считаете нужным. Проверьте таблицу ниже для полного списка параметров:
Swashbuckle.aspnetcore.swagger
Измените путь для Swagger json конечные точки
Изменить Swagger с помощью контекста запроса
Serialize Swagger JSON в формате 2.0
Работа с виртуальными каталогами и обратными прокси
Настройка того, как сериализован документ OpenAPI
Swashbuckle.aspnetcore.swaggergen
Назначить явные операции
Список операций ответов
Требуются параметры и свойства схемы
Обрабатывать формы и загрузки файлов
Обрабатывать загрузки файлов
Включите описания из комментариев XML
Предоставьте глобальные метаданные API
Генерировать несколько документов Swagger
Опустите устаревшие операции и/или свойства схемы
Опустить произвольные операции
Настроить операционные теги (например, для группировки пользовательского интерфейса)
Изменить заказ сортировки операции (например, для сортировки пользовательского интерфейса)
Настроить идентификаторы схемы
Переопределить схему для конкретных типов
Расширить генератор с помощью операции, фильтров схемы и документов
Добавить определения и требования безопасности
Добавьте определения безопасности и требования к Auth Searer Auth
Наследование и полиморфизм
Swashbuckle.aspnetcore.swaggerui
Изменить относительный путь к пользовательскому интерфейсу
Изменить заголовок документа
Изменить пути CSS или JS
Перечислить несколько документов Swagger
Применить параметры Swagger-UI
Inject Custom JavaScript
Inject Custom CSS
Настроить index.html
Включить потоки OAuth2.0
Используйте запрос на сторону клиента и перехватчики ответов
Swashbuckle.aspnetcore.annotations
Установить и включить аннотации
Операция по обогащению метаданных
Метаданные ответа обогащения
Метаданные параметров обогащения
Enrich запроса метаданных
Метаданные схемы обогащения
Применить схемы фильтров к конкретным типам
Добавьте метаданные метки
Swashbuckle.aspnetcore.cli
Получить Swagger непосредственно с сборки стартапа
Используйте инструмент CLI с пользовательской конфигурацией хоста
Swashbuckle.aspnetcore.redoc
Изменить относительный путь к пользовательскому интерфейсу
Изменить заголовок документа
Применить параметры REDOC
Inject Custom CSS
Настроить index.html
По умолчанию Swagger JSON будет выставлен по следующему маршруту - "/swagger/{ documentName/SWAGGER.JSON". При необходимости вы можете изменить это при включении промежуточного программного обеспечения Swagger. Пользовательские маршруты должны включать параметр {documentName} .
app.useswagger (c => {c.routeTemplate = "api-docs/{documentName}/swagger.json";})Примечание. Если вы используете промежуточное программное обеспечение Swaggerui, вам также необходимо обновить его конфигурацию, чтобы отразить новые конечные точки:
app.useswaggerui (c => {c.swaggerendpoint ("/api-docs/v1/swagger.json", "my api v1");})ПРИМЕЧАНИЕ. Если вам также нужно обновить относительный путь, на котором доступен сам пользовательский интерфейс, вам нужно следовать инструкциям, найденным в относительном пути изменения к пользовательскому интерфейсу.
Если вам нужно установить некоторые метаданные Swagger на основе текущего запроса, вы можете настроить фильтр, выполненный до сериализации документа.
app.useswagger (c => {c.preserializefilters.add ((Swagger, httpreq) => {swagger.servers = new List <ponapisterver> {new OpenApierver {url = $ "{httpreq.scheme}: // {httpreq. Host.value} "}};});}); OpenApiDocument и текущий HttpRequest передаются в фильтр. Это обеспечивает большую гибкость. Например, вы можете добавить явный сервер API на основе заголовка «хост» (как показано), или вы можете проверить информацию сеанса или заголовок авторизации и удалить операции из документа на основе разрешений пользователей.
По умолчанию Swashbuckle будет генерировать и разоблачить Swagger JSON в версии 3.0 спецификации, официально названной спецификацией OpenAPI. Однако, чтобы поддержать обратную совместимость, вы можете продолжить разоблачение его в формате 2.0 со следующим вариантом:
app.useswagger (c => {c.serializeasv2 = true;}); Виртуальные каталоги и обратные прокси могут вызвать проблемы для приложений, которые генерируют ссылки и перенаправления, особенно если приложение возвращает абсолютные URL -адреса на основе заголовка Host и другой информации из текущего запроса. Чтобы избежать этих проблем, Swashbuckle использует относительные URL -адреса, где это возможно, и поощряет их использование при настройке промежуточного программного обеспечения Swaggerui и Redoc.
Например, чтобы подключить промежуточное программное обеспечение Swaggerui, вы предоставляете URL -адрес одно или несколько документов OpenAPI/Swagger. Это URL, который Swagger-UI, приложение на стороне клиента, позвонит, чтобы получить ваши метаданные API. Чтобы убедиться, что это работает за виртуальными каталогами и обратными прокси, вы должны выразить это относительно RoutePrefix самого Swagger-UI:
app.useswaggerui (c => {c.routeprefix = "swagger"; c.swagerendpoint ("v1/swagger.json", "my api v1");}); ПРИМЕЧАНИЕ. В предыдущих версиях документов вы, возможно, видели это в качестве корневой связи (EG /swagger/v1/swagger.json ). Это не сработает, если ваше приложение будет размещено в виртуальном каталоге IIS или за прокси, который переполняет путь запроса перед пересылкой. Если вы переключитесь на обратный синтаксис, показанный выше, он должен работать во всех случаях.
По умолчанию Swashbuckle будет сериализовать документ OpenAPI, используя методы Serialize на объекте Document OpenAPI. Если требуется индивидуальная сериализация, можно создать пользовательский сериализатор документа, который реализует интерфейс ISwaggerDocumentSerializer . Это может быть установлено на SwaggerOptions в коллекции услуг с использованием ConfigureSwagger() :
Примечание
Если вы планируете использовать инструмент командной строки для генерации файлов спецификации OpenAPI, это должно быть сделано в коллекции служб, используя ConfigureSwagger() .
services.configureswagger (options => {option.setCustomDocumenterErializer <campaintocumenterializer> ();})Когда инструмент командной строки не используется, он также может быть сделан на хосте приложения:
app.useswagger (options => {options.setCustomDocumenterErializer <CampactDocumenterErializer> ();}) В Swagger операции могут быть назначены operationId . Этот идентификатор должен быть уникальным среди всех операций, описанных в API. Инструменты и библиотеки (например, генераторы клиентов) могут использовать OperationID для уникального идентификации операции, поэтому рекомендуется следовать общим соглашениям по именованию программирования.
Автопроизводство идентификатор, соответствующий эти требования, а также предоставление имени, которое будет иметь значение в клиентских библиотеках, является нетривиальной задачей, и поэтому Swashbuckle по умолчанию опускает operationId . Однако, если это необходимо, вы можете назначить operationIds , украшая отдельные маршруты или предоставляя пользовательскую стратегию.
Вариант 1) Украсить маршруты с помощью Name свойства
[Httpget ("{id}", name = "getProductbyId")] public iActionResult get (int id) // anpormation ad = "getProductbyId"Вариант 2) Предоставьте пользовательскую стратегию
// startup.csservices.addswaggergen (c => {... // Использовать имя метода в качестве операции c.customoperationids (apidesc => {return apidesc.trygetmethodinfo (out methodinfo methodinfo)? Methodinfo.name: null;});} ) // productscontroller.cs [httpget ("{id}")] public iActionResult getProductbyId (int id) // anpormationid = "getProductbyId" Примечание. При любом подходе авторы API несут ответственность за обеспечение уникальности operationIds по всем операциям
По умолчанию Swashbuckle генерирует ответ «200» для каждой операции. Если действие возвращает DTO -ответ, то это будет использоваться для генерации схемы для тела ответа. Например ...
[Httppost ("{id}")] открытый продукт Getbyid (int id)Создаст следующие метаданные ответа:
responses: {
200: {
description: "OK",
content: {
"application/json": {
schema: {
$ref: "#/components/schemas/Product"
}
}
}
}
} Если вам необходимо указать другой код состояния и/или дополнительные ответы, или ваши действия возвращают IActionResult вместо DTO ответа, вы можете явно описать ответы с помощью ProducesResponseTypeAttribute , которые отправляются с ядро ASP.NET. Например ...
[Httppost ("{id}")] [ProductesResponseType (typeof (product), 200)] [PresectesResponsEtype (typeof (Idication <String, String>), 400)] [ProductesResponseType (500)] public iActionResult getByid (int id)Создаст следующие метаданные ответа:
responses: {
200: {
description: "OK",
content: {
"application/json": {
schema: {
$ref: "#/components/schemas/Product"
}
}
}
},
400: {
description: "Bad Request",
content: {
"application/json": {
schema: {
type: "object",
additionalProperties: {
type: "string"
}
}
}
}
},
500: {
description: "Internal Server Error",
content: {}
}
} В документе Swagger вы можете пометить параметры и свойства схемы, которые необходимы для запроса. Если параметр (верхний уровень или на основе свойств) украшен BindRequiredAttribute или RequiredAttribute , то Swashbuckle автоматически помечает его как «требуемый» параметр в сгенерированном чваньке:
// ProductsController.Cspublic iActionResult Search ([[ormquery, bindrequired] String Keywords, [utquery] pagingparams pagingparams) {if (! ModelState.isvalid) возвращает BadRequest (ModelState); ...} // SearchParams.cspublic Class Papparams {[обязательный ] public int pageno {get; набор; } public int PageSize {get; набор; }} В дополнение к параметрам, Swashbuckle также выполнит RequiredAttribute при использовании в модели, которая связана с корпусом запроса. В этом случае украшенные свойства будут помечены как «требуемые» свойства в описании тела:
// productsController.cspublic iActionResult create ([frombody] продукт продукта) {if (! Modelstate.isvalid) return badrequest (modelstate); ...} // product.cspublic class product {[требуется] public String name {get; набор; } public String Описание {get; набор; }}Этот контроллер примет два значения поля формы и один из именованных файлов загрузки из одной и той же формы:
[Httppost] public void uploadfile ([fromform] string description, [fromform] datetime clientdate, файл iformfile)
Важное примечание. Согласно документам ASP.NET Core, вы не должны украшать параметры
IFormFileс атрибутом[FromForm], поскольку источник связывания автоматически выводится из типа. Фактически, предполагаемым значением являетсяBindingSource.FormFile, и если вы примените атрибут, он будет установлен наBindingSource.Form, который обладаетApiExplorer, компонентом метаданных, который поставляется с ядром ASP.NET и в сильно опирается Swashbuckle. Одна конкретная проблема здесь заключается в том, что Swaggerui не будет рассматривать параметр как файл и поэтому не будет отображать кнопку загрузки файла, если вы ошибочно включаете этот атрибут.
ApiExplorer (компонент метаданных ядра ASP.NET, на котором строится Swashbuckle) не появляется по умолчанию Produces FileResult , и поэтому вам необходимо явно сказать его с атрибутом ProducesResponseType .
[Httpget ("{filename}")] [ProductsResponsetype (typeof (fileStreamResult), Statestcodes.status200ok, "Image/jpeg")] publiceReamResult getFile (String fileName)Чтобы улучшить сгенерированные документы с помощью дружественных к человеку описаниям, вы можете аннотировать действия и модели контроллера с помощью XML-комментариев и настроить Swashbuckle, чтобы включить эти комментарии в вывод Swagger Json:
Откройте диалоговое окно «Свойства» для вашего проекта, нажмите на вкладку «Строительница» и убедитесь, что «файл документации XML» проверяется, или добавьте <GenerateDocumentationFile>true</GenerateDocumentationFile> элемент в раздел <PropertyGroup> вашего файла проекта .CSPROJ. Это создаст файл, содержащий все комментарии XML во время сборки.
На этом этапе любые классы или методы, которые не аннотированы с помощью комментариев XML, вызовут предупреждение по сборке. Чтобы подавить это, введите код предупреждения «1591» в поле «Предупреждения« подавить »в диалоговом окне« Свойства »или« Добавить <NoWarn>1591</NoWarn> в раздел <PropertyGroup> вашего файла проекта .csproj.
Настройте Swashbuckle, чтобы включить XML -комментарии к файлу в сгенерированный Swagger Json:
services.addswaggergen (c => {c.swaggerdoc ("v1", new openapiinfo {title = "my api - v1", version = "v1"}); c.includexmlcomments (assembly.getExecutingAssembly ()); // или или или или или c.includexmlcomments (typeof (mycontroller). Assembly));}Аннотируйте свои действия с помощью резюме, замечаний, параметров и ответных тегов:
/// <summary> /// Извлекая конкретный продукт с помощью уникального идентификатора /// </summary> /// <Remarks> awesomensy! </remarks> /// <param name = "id" Пример = "123" > Идентификатор продукта </param> /// <code = "200"> Получено продукт </response> /// <code = "404"> Продукт не найден </response> /// <code = = "500"> упс! Не могу поискать ваш продукт прямо сейчас </response> [httpget ("{id}")] [PreseersResponseType (typeof (Product), 200)] [ProductesResponseType (404)] [Производство. идентификатор)Вы также можете аннотировать типы с помощью резюме и примеров тегов:
Public Class Product {/// <summary> /// Название продукта /// </summary> /// <Пример> Мужская баскетбольная обувь </Пример> Публичная строка name {get; набор; } //// <summary> /// Количество, оставшееся в наличии /// </summary> /// <Пример> 10 </revence> public int vieflestock {get; набор; } //// <summary> /// Размеры, которые продукт доступен в /// </summary> /// <Пример> ["Small", "Medium", "large"] </arvess> public list < string> размеры {get; набор; }}Восстановите свой проект, чтобы обновить файл комментариев XML и перейти к конечной точке Swagger JSON. Обратите внимание, как описания отображаются на соответствующих полях чванства.
Примечание. Вы также можете предоставить описания схемы Swagger, аннотируя ваши модели API и их свойства сводными тегами. Если у вас есть несколько файлов комментариев XML (например, отдельные библиотеки для контроллеров и моделей), вы можете вызвать метод includexmlcomments несколько раз, и все они будут объединены в вывод Swagger JSON.
В дополнение к «Pathitems», «Operations» и «ответам», которые Swashbuckle генерирует для вас, Swagger также поддерживает глобальные метаданные (см. Https://swagger.io/speciation/#oasobject). Например, вы можете предоставить полное описание для вашего API, условий обслуживания или даже контактной и лицензионной информации:
c.swaggerdoc ("v1", new openapiinfo {title = "my api - v1", version = "v1", description = "Пример API для демонстрации Swashbuckle", термины service = new uri ("http://tempuri.org /Условия "), contact = new OpenApicontact {name =" Joe Developer ", email =" [email protected] "}, лицензия = new OpenApilicense {name =" apache 2.0 ", url = new URI (" https: //www.apache.org/licenses/license-2.0.html ")}});Совет: используйте Intellisense, чтобы увидеть, какие другие области доступны.
С настройкой, описанной выше, генератор будет включать все операции API в одном документе Swagger. Тем не менее, вы можете создать несколько документов, если это необходимо. Например, вам может понадобиться отдельный документ для каждой версии вашего API. Чтобы сделать это, начните с определения нескольких докторов Swagger в Startup.cs :
services.addswaggergen (c => {c.swaggerdoc ("v1", new openapiinfo {title = "my api - v1", version = "v1"}); c.swaggerdoc ("v2", new openapiinfo {title = " My API - v2 ", version =" v2 "});})Обратите внимание на первый аргумент в Swaggerdoc. Это должно быть удобное для URI имени, которое однозначно идентифицирует документ. Впоследствии он используется для создания пути для запроса соответствующего чванства JSON. Например, с помощью маршрутизации по умолчанию приведенные выше документы будут доступны по адресу "/swagger/v1/swagger.json" и "/swagger/v2/swagger.json".
Затем вам нужно сообщить Swashbuckle, какие действия включать в каждый документ. Хотя это можно настроить (см. Ниже), по умолчанию генератор будет использовать свойство ApiDescription.GroupName , часть встроенного уровня метаданных, который поставляется с ядром ASP.NET, чтобы провести это различие. Вы можете установить это, украшая отдельные действия или применив соглашение об широком приложении.
Чтобы включить действие в конкретный документ Swagger, украсьте его с помощью ApiExplorerSettingsAttribute и установить GroupName на соответствующее имя документа (чувствительное к делу):
[Httppost] [apiexplorersettings (groupname = "v2")] public void post ([от продукта по теле]) продукт)
Чтобы группировать по соглашению, вместо того, чтобы украсить каждое действие, вы можете применить пользовательский контроллер или соглашение о действии. Например, вы можете подключить следующее соглашение, чтобы назначить действия документам на основе пространства имен контроллера.
// apiexplorergroupperversionConvention.cspublic class apiexplorergroupperversionconvention: icontrollermodelconvention {public void Apply (ControlModel Controller) {var controlerNamespace = controller.ControllerType.namespace; // Например, "Controllers.v1" var apiversion = controlerNamespace.split ('.'). Last (). ToLower (); controller.apiexplorer.groupName = apiversion;}} // startup.cspublic void configureservices (servicecollection services) { services.addmvc (c => c.conventions.add (new apiexplorergroupperversionconvention ())); ...} При выборе действий для данного документа Swagger генератор вызывает DocInclusionPredicate против каждой ApiDescription , которая появляется в рамках. Реализация по умолчанию осматривает ApiDescription.GroupName . Тем не менее, вы также можете предоставить предикат индивидуального включения. Например, если вы используете подход, основанный на атрибутах, для реализации версий API (например, microsoft.aspnetcore.mvc.versioning), вы можете настроить пользовательский предикат, который вместо этого использует атрибуты управления версией:
c.docinclusionpredicate ((docname, apidesc) => {if (! apidesc.trygetmethodinfo (out methodinfo methodinfo))) вернуть false; var versions = methodinfo.declaringtype .getCustmattributes (true) .oftype <piversionattribute> (). > attr.versions); Если вы используете промежуточное программное обеспечение SwaggerUI , вам нужно указать любые дополнительные конечные точки Swagger, которые вы хотите разоблачить. Смотрите список нескольких документов Swagger для получения дополнительной информации.
Спецификация Swagger включает в себя deprecated флаг для указания того, что операция устарела и должна быть воздержана от использования. Генератор Swagger автоматически установит этот флаг, если соответствующее действие будет украшено с помощью ObsoleteAttribute . Однако вместо установки флага вы можете настроить генератор, чтобы вообще игнорировать устаревшие действия:
services.addswaggergen (c => {... c.ignoreobsoleteactions ();}; Аналогичный подход также может быть использован для охлаждения устаревших свойств из схем в выводе Swagger. То есть вы можете украсить свойства модели с помощью ObsoleteAttribute и настроить Swashbuckle, чтобы опустить эти свойства при генерации схем JSON:
services.addswaggergen (c => {... c.ignoreobsoleteproperties ();};Вы можете опустить операции из вывода Swagger, украшая отдельные действия или применяя соглашение об широком приложении.
Чтобы пропустить конкретное действие, украсьте его с помощью ApiExplorerSettingsAttribute и установите флаг IgnoreApi :
[Httpget ("{id}")] [apiexplorersettings (IgnoreApi = true)] public product getbyid (int id)Чтобы опустить действия по соглашению, вместо того, чтобы украсить их индивидуально, вы можете применить пользовательскую конвенцию о действиях. Например, вы можете подключить следующее соглашение только для документирования операций GET:
// apiexplorergetsonlyconvention.cspublic class apiexplorergetsonlyconvention: iActionModelConvention {public void Apply (ActionModel Action) {action.apexplorer.isvisible = action.attributes.oftype <httpgetattribute> () нанесение Services) {services.addmvc (c => c.conventions.add (new apiexplorergetsonlyconvention ()); ...} Спецификация Swagger позволяет назначать один или несколько «тегов» для операции. Генератор Swagger назначит имя контроллера в качестве тега по умолчанию. Это важно отметить, если вы используете промежуточное программное обеспечение SwaggerUI , поскольку оно использует это значение для групповых операций.
Вы можете переопределить тег по умолчанию, предоставив функцию, которая применяет теги по соглашению. Например, следующая конфигурация будет отмечать, и поэтому групповые операции в пользовательском интерфейсе методом HTTP:
services.addswaggergen (c => {... c.tagactionsby (api => api.httpmethod);};По умолчанию действия назначаются назначенным тегом (см. Выше), прежде чем они сгруппированы в вложенную структуру Swagger Spec. Но вы можете изменить заказ действий по умолчанию с помощью пользовательской стратегии сортировки:
Services.AddsWaggerGen (c => {... C.OrderActionsby ((apidesc) => $ "{apidesc.actiondescriptor.routevalues [" controller "]} _ {apidesc.httpmethod}");};Примечание. Это диктует порядок сортировки до того, как действия будут сгруппированы и превращаются в формат чванства. Таким образом, это влияет на упорядочение групп (то есть Swagger «Pathitems») и на упорядочение операций в группе, в выводе Swagger.
Если генератор встречается с сложным параметром или типами ответов, он будет генерировать соответствующую схему JSON, добавить ее в словарь глобальных components/schemas и ссылаться на ее из описания операции с помощью уникального идентификатора. Например, если у вас есть действие, которое возвращает тип Product , то сгенерированная схема будет ссылаться следующим образом:
responses: {
200: {
description: "OK",
content: {
"application/json": {
schema: {
$ref: "#/components/schemas/Product"
}
}
}
}
} Однако, если он встречается с несколькими типами с одинаковым именем, но разными пространствами имен (например, RequestModels.Product & ResponseModels.Product ), то Swashbuckle поднимет исключение из -за «противоречивых схем». В этом случае вам нужно предоставить стратегию пользовательской идентификации, которая дополнительно квалифицирует имя:
services.addswaggergen (c => {... c.customschemaids ((type) => type.fullname);};См. #2703 для поддержки вложенных типов.
Задача с коробкой, Swashbuckle выполняет приличную работу по созданию схем JSON, которые точно описывают ваш запрос и полезные нагрузки ответов. Однако, если вы настраиваете поведение сериализации для определенных типов в вашем API, вам может потребоваться помочь.
Например, у вас может быть класс с несколькими свойствами, которые вы хотите представлять в JSON в качестве запятой. Для этого вы, вероятно, реализуете пользовательский JsonConverter . В этом случае Swashbuckle не знает, как реализован конвертер, и поэтому вам нужно предоставить его схемой, которая точно описывает тип:
// phonenumber.cspublic class phonenumber {public String CountryCode {get; набор; } public String reacode {get; набор; } public String abscriberid {get; набор; }} // startup.csservices.addswaggergen (c => {... c.maptype <phonenumber> (() => new openapischema {type = "string"});};Swashbuckle обнажает трубопровод фильтров, который зацепляется в процесс генерации. После создания отдельные объекты метаданных передаются в трубопровод, где их можно изменить дальше. Вы можете подключить пользовательские фильтры для обогащения сгенерированных «операций», «схем» и «документов».
Swashbuckle извлекает ApiDescription , часть Core ASP.NET, для каждого действия и использует его для генерации соответствующего OpenApiOperation . После создания он проходит OpenApiOperation и ApiDescription через список настроенных рабочих фильтров.
В типичной реализации фильтра вы будете осмотреть ApiDescription на наличие соответствующей информации (например, информация о маршруте, атрибуты действия и т. Д.), А затем обновите соответствующим образом OpenApiOperation . Например, в следующем фильтре перечислены дополнительный ответ «401» для всех действий, которые украшены AuthorizeAttribute
// AuthresponseSoperationFilter.cspublic Class Authresponsesoperationfilter: ioperationfilter {public void Apply (OpenApioperation Operation, OperationFilterContext) <AuthorizEatTribute > (); if (Authattributes.Any ()) operation.Responses.Add ("401", new OpenApiresponse {description = "unauthorized"});}} // startup.csservices.addswaggergen (c => {... C.OperationFilter <authresponseseperationfilter> ();};ПРИМЕЧАНИЕ. Фильтрующие трубопроводы Di-Aware. То есть вы можете создавать фильтры с параметрами конструктора, и если типы параметров зарегистрированы в DI Framework, они будут автоматически вводить при создании фильтров
Swashbuckle генерирует Jsonschema Jsonschema со вкусом чванства для каждого параметра, ответа и типа свойства, которые выявляются вашими действиями контроллера. После создания он проходит схему и вводит в список настроенных фильтров схемы.
Приведенный ниже пример добавляет расширение поставщика AutoRest (см. Https://github.com/azure/autorest/blob/master/docs/extensions/readme.md#x-ms-enum), чтобы сообщить инструменту AutoRest, как должны быть моделированы enums. Когда он генерирует клиент API.
// AutorestSchemafilter.cspublic Class Autorestschemafilter: ischemafilter {public void Apply (openapischema schema, cemafiltercontext context) {var type = context.type; if (type.isenum) {schema.extensions.add ("x-ms-enum", new. OpenApiObject {["name"] = new OpenApistring (type.name), ["modelAssTring"] = new OpenApiboolean (true)});};}} // startup.csservices.addswaggergen (c => {... c .Schemafilter <autorestschemafilter> ();}; Пример ниже позволяет создать автоматическую схему универсального Dictionary<Enum, TValue> объектов. Обратите внимание, что это только генерирует чванство; System.Text.Json не может разобрать в словарном переводе по умолчанию, поэтому вам понадобится специальный JSONConverter, как в документах .NET.
// DictionaryTKeyEnumtvalueschemafilter.cspublic Class DictionaryTKeyEnumTvalueschemafilter: ischemafilter {
Применить Public void (схема Openapischema, контекст SchemafilterContext)
{// Работайте только для полей, которые являются словарем <enum, tvalue> if (! Context.type.isgenerictype ||! Context.type.getgenerictypenefinition (). Isassignablefrom (typeof (dictionary <,>))) {return;} var keytype = context.type.getgenericarguments () [0]; var valuetype = context.type.getgenericarguments () [1]; if (! keytype.isenum) {return;} schema.type = "Object"; = keytype.getenumnames (). todictionary (name => name, name => context.schemagenerator.generateschema (valuetype, context.schemarepository));
}} // startup.csservices.addswaggergen (c => {... // Они будут заменены словарями .c.maptype <Dictionary <myenum, list <string >>> (() => new OpenApischema ()); C.schemafilter <dictionarytkeeNumtvalueschemafilter> ();}; После того, как OpenApiDocument был сгенерирован, его также можно пропустить через набор предварительно сконфигурированных фильтров документов. Это дает полное управление для изменения документа, как вы считаете подходящим. Чтобы убедиться, что вы все еще возвращаете действительный Swagger JSON, вы должны прочитать спецификацию перед использованием этого типа фильтра.
Пример ниже приведен описание для любых тегов, которые назначены операциям в документе:
Общедоступный класс TagdescriptionsDocumentFilter: IdocumentFilter {public void Apply (OpenApidocument SwaggerDoc, DocumentFilterContext Context) {SwaggerDoc.tags = новый список <ponpaPitag> {new OpenApitag {name = "Продукты", описание = "Просмотр/Управление каталогом продукта"}, New OpenApitag {Name = "orders", description = "Отправить заказы"}};}} Примечание. Если вы используете промежуточное программное обеспечение SwaggerUI , TagDescriptionsDocumentFilter продемонстрированное выше, может быть использовано для отображения дополнительных описаний помимо каждой группы операций.
В Swagger вы можете описать, как ваш API защищен путем определения одной или нескольких схем безопасности (например, Basic, API -ключа, OAuth2 и т. Д.) И объявления, какие из этих схем применимы во всем мире или для конкретных операций. Для получения более подробной информации взгляните на объект требований безопасности в Swagger Spec ..
В Swashbuckle вы можете определить схемы, вызывая метод AddSecurityDefinition , предоставляя имя и экземпляр OpenApiSecurityScheme . Например, вы можете определить OAuth 2.0 - неявный поток следующим образом:
// startup.csservices.addswaggergen (c => {... // определить схему OAuth2.0, которая используется (то есть неявное поток) c.AddsecurityDefinition ("OAuth2", New OpenApisecurityScheme {type = securitySchemetype.oAuth2, flows = new OpenApioAuthflows {intize = new OpenApioAuthflow {AuthorizationUrl = new URI ("/auth-server/connect/Authorize", urikind.relative), scopes = new Dictionary <string, string> {{"readaccess", "access hopection"} , {"writeAccess", "access write operations"}}}}});}; Примечание. В дополнение к определению схемы, вам также необходимо указать, к какой операции применима эта схема. Вы можете применять схемы по всему миру (т.е. ко всем операциям) с помощью метода AddSecurityRequirement . Приведенный ниже пример указывает на то, что схема, называемая «OAuth2», должна применяться ко всем операциям, и что требуются области «ReadAccess» и «writeAccess». При применении схем типа, кроме «OAuth2», массив областей должен быть пустым.
C.AddswaggerGen (c => {... c.AddsecurityRequirement (new OpenApiseCerationRequirement {{new OpenApiseCerationScheme {reference = new OpenApireference {type = serficeType.securityScheme, id = "oauth2"}, new [] {"readaccess", " writeAccess "}}});}) Если у вас есть схемы, которые применимы только к определенным операциям, вы можете применить их через операционный фильтр. Например, следующий фильтр добавляет требования OAuth2 на основе присутствия AuthorizeAttribute :
// SecurityRequirementsOperationFilter.cspublic Class SecurityRequirementsOperationFilter: ioperationFilter {public void Apply (OpenApioperation Operation, OperationFilterContext Context) {// Имена политики MAP для scopesvar redingscopes = context.methodinfo.getcustomattributes (true). > attr.policy) .distinct (); if (redectyscopes.any ()) {anpormation.responses.add ("401", new OpenApiresponse {description = "unauthorized"}); Operation.Responses.Add ("403", new OpenApiresponse {description = "forbidden"}); var Oauthscheme = new OpenApiseCerationScheme {repartion = new OpenApireference {type = serireceType.securityScheme, id = "oauth2"}}; Operation.Security = new ListCecurityRecure oauthscheme] = redingscopes.tolist ()}};}}} ПРИМЕЧАНИЕ. Если вы используете промежуточное программное обеспечение SwaggerUI , вы можете включить интерактивные потоки OAuth2.0, которые оснащены испускаемыми метаданными безопасности. См. Включение потоков OAuth2.0 для получения более подробной информации.
Services.AddsWaggerGen (c => {c.AddsecurityDefinition ("BeareraUth", New OpenApisecurityScheme {type = securitySchemetype.http, Scheme = "Beerer", Bearerformat = "jwt", description = "jwt Aproader Header с использованием схемы носителя."}. ); Swagger / OpenAPI определяет ключевые слова allOf и oneOf для описания отношений наследования и полиморфизма в определениях схемы. Например, если вы используете базовый класс для моделей, которые разделяют общие свойства, вы можете использовать ключевое слово allOf для описания иерархии наследования. Или, если ваш сериализатор поддерживает полиморфную сериализацию/десериализацию, вы можете использовать ключевое слово oneOf для документирования всех «возможных» схем для запросов/ответов, которые варьируются в зависимости от подтипа.
По умолчанию Swashbuckle сглаживает иерархии наследования. То есть для производных моделей унаследованные свойства объединяются и перечислены вместе с объявленными свойствами. Это может вызвать много дублирования в сгенерированном чванстве, особенно когда есть несколько подтипов. Это также проблематично, если вы используете генератор клиента (например, NSWAG) и хотели бы сохранить иерархию наследования в сгенерированных клиентских моделях. Чтобы обойти это, вы можете применить настройку UseAllOfForInheritance , и это будет использовать ключевое слово allOf для включения наследственных свойств путем ссылки в сгенерированном чванстве:
Circle: {
type: "object",
allOf: [
{
$ref: "#/components/schemas/Shape"
}
],
properties: {
radius: {
type: "integer",
format: "int32",
}
},
},
Shape: {
type: "object",
properties: {
name: {
type: "string",
nullable: true,
}
},
} Если ваш сериализатор поддерживает полиморфную сериализацию/десериализацию, и вы хотели бы перечислить возможные подтипы для действия, которое принимает/возвращает абстрактные типы базовых типов, вы можете применить настройку UseOneOfForPolymorphism . В результате сгенерированные схемы запроса/ответа будут ссылаться на сбор «возможных» схем вместо схемы базового класса:
requestBody: {
content: {
application/json: {
schema: {
oneOf: [
{
$ref: "#/components/schemas/Rectangle"
},
{
$ref: "#/components/schemas/Circle"
},
],
}
}
}Поскольку отношения наследования и полиморфизма часто могут стать довольно сложными, не только в ваших собственных моделях, но и в библиотеке класса .NET, Swashbuckle избирательен относительно того, какие иерархии он делает, и не подвергается в созданном чванстве. По умолчанию он подберит любые подтипы, которые определены в той же сборке, что и заданный базовый тип. Если вы хотите переопределить это поведение, вы можете предоставить пользовательскую функцию селектора:
services.addswaggergen (c => {... c.useallofforinhericance (); c.selectsubtypesusing (basetype => {return typeof (startup) .assembly.gettypes (). где (type => type.issubclassof (baseType)); })}); Примечание. Если вы используете библиотеку аннотаций Swashbuckle, она содержит пользовательский селектор, который основан на наличии атрибутов SwaggerSubType на определениях базовых классов. Таким образом, вы можете использовать простые атрибуты, чтобы явно перечислить отношения наследования и/или полиморфизма, которые вы хотите разоблачить. Чтобы включить это поведение, ознакомьтесь с документами аннотаций.
В сочетании с ключевыми словами oneOf и / или allOf Swagger / OpenAPI поддерживает поле discriminator по определениям базовых схемы. Это ключевое слово указывает на свойство, которое идентифицирует конкретный тип, представленный данной полезной нагрузкой. В дополнение к имени свойства, описание дискриминатора также может включать mapping , которое отображает значения дискриминатора с конкретными определениями схемы.
Например, Newtonsoft Serializer поддерживает полиморфную сериализацию/десериализацию, излучая/принимая свойство «типа $» в экземпляры JSON. Значением этого свойства будет имя квалифицированного типа сборочного типа типа, представленного данным экземпляром JSON. Таким образом, чтобы явно описать это поведение в чванстве, соответствующая схема запроса/ответа может быть определена следующим образом:
components: {
schemas: {
Shape: {
required: [
"$type"
],
type: "object",
properties: {
$type: {
type": "string"
},
discriminator: {
propertyName: "$type",
mapping: {
Rectangle: "#/components/schemas/Rectangle",
Circle: "#/components/schemas/Circle"
}
}
},
Rectangle: {
type: "object",
allOf: [
{
"$ref": "#/components/schemas/Shape"
}
],
...
},
Circle: {
type: "object",
allOf: [
{
"$ref": "#/components/schemas/Shape"
}
],
...
}
}
} Если UseAllOfForInheritance или UseOneOfForPolymorphism включен, и ваш сериализатор поддерживает (и включает) излучение/принятие свойства дискриминатора, то Swashbuckle автоматически генерирует соответствующие метаданные discriminator на определениях базовых схемы.
В качестве альтернативы, если вы настроили свой сериализатор для поддержки полиморфной сериализации/десериализации, вы можете предоставить некоторые пользовательские функции селектора для определения имени дискриминатора и соответствующего отображения:
services.addswaggergen (c => {... c.useOneOfforinHeritance (); C.SelectDiscriminAtornameUsing ((Basetype) => "typename"); C.selectDiscriminatorValueUsing ((subtype) => subtype.name);}); Примечание. Если вы используете библиотеку аннотаций Swashbuckle, она содержит пользовательские функции селектора, которые основаны на наличии атрибутов SwaggerDiscriminator и SwaggerSubType на определениях базовых классов. Таким образом, вы можете использовать простые атрибуты для явного обеспечения метаданных дискриминатора. Чтобы включить это поведение, ознакомьтесь с документами аннотаций.
По умолчанию пользовательский интерфейс Swagger будет выставлен в "/Swagger". При необходимости вы можете изменить это при включении промежуточного программного обеспечения Swaggerui:
app.useswaggerui (c => {c.routeprefix = "api-docs"}По умолчанию пользовательский интерфейс Swagger будет иметь общий заголовок документа. Когда у вас открывается несколько страниц Swagger, их может быть трудно отделить. Вы можете изменить это при включении промежуточного программного обеспечения Swaggerui:
app.useswaggerui (c => {c.documenttitle = "my swagger UI";}По умолчанию пользовательский интерфейс Swagger включает в себя CSS и JS по умолчанию, но если вы хотите изменить путь или URL (например, для использования CDN):
app.useswaggerui (c => {c.stylespath = "https://cdnjs.cloudflare.com/ajax/libs/swagger-ui/5.17.10/swagger-ui.min.css"; c.scriptbundlepath = "https : //cdnjs.cloudflare.com/ajax/libs/swagger-ui/5.17.10/swagger-ui-bundle.min.js "; c.scriptpresetspath =" https://cdnjs.cloudflare.com/ajax/libs /swagger-ui/5.17.10/swagger-ui-standalone-preset.min.js ";}При включении промежуточного программного обеспечения вам необходимо указать одну или несколько конечных точек Swagger (полностью квалифицированные или относительно страницы пользовательского интерфейса) для питания пользовательского интерфейса. Если вы предоставите несколько конечных точек, они будут перечислены в правом верхнем углу страницы, что позволит пользователям переключаться между различными документами. Например, следующая конфигурация может быть использована для документирования различных версий API.
app.useswaggerui (c => {c.swaggerendpoint ("/swagger/v1/swagger.json", "v1 docs"); c.swagerendpoint ("/swagger/v2/swager.json", "v2 документы"); }Swagger-UI отправляется со своим собственным набором параметров конфигурации, все описаны здесь. В Swashbuckle большинство из них всплывают через варианты промежуточного программного обеспечения Swaggerui:
app.useswaggerui (c => {c.defaultmodelexpanddepth (2); c.defaultmodelrendering (modelrendering.model); c.defaultmodelsexpanddepth (-1); c.displayoperationid (); c.displayRequestdaturation (); c.docexpansion (docexpansion. Нет); [Mycustoplugin »]; ) => {return response;} ");});Примечание
При добавлении пользовательских плагинов убедитесь, что вы добавляете любые пользовательские файлы js , которые определяют функцию плагина.
Чтобы настроить поведение, вы можете ввести дополнительные файлы JavaScript, добавив их в свою папку wwwroot и указав относительные пути в параметрах промежуточного программного обеспечения:
app.useswaggerui (c => {c.injectjavascript ("/swagger-ui/custom.js");} ПРИМЕЧАНИЕ. Опции InjectOnCompleteJavaScript и InjectOnFailureJavaScript были удалены, поскольку последняя версия Swagger-UI не выявляет необходимые крючки. Вместо этого он предоставляет гибкую систему настройки, основанную на концепциях и шаблонах от React и Redux. Чтобы использовать это, вам нужно предоставить пользовательскую версию index.html, как описано ниже.
Пример примера индекса индекса демонстрирует этот подход, используя систему плагина Swagger-UI, предоставляя пользовательскую Topbar и скрыть информационный компонент.
Чтобы настроить внешний вид, вы можете ввести дополнительные таблицы стилей CSS, добавив их в свою папку wwwroot и указав относительные пути в параметрах промежуточного программного обеспечения:
app.useswaggerui (c => {c.injectstylesheet ("/swagger-ui/custom.css");}Чтобы настроить пользовательский интерфейс помимо основных вариантов, перечисленных выше, вы можете предоставить свою собственную версию страницы Swagger-UI Index.html:
app.useswaggerui (c => {c.indexstream = () => getType (). Assembly .getManifestresourcestream ("customUiindex.swager.index.html"); // Требует добавления файла в виде встроенного ресурса});Чтобы начать, вы должны основывать свой пользовательский index.html на версии по умолчанию
Swagger-UI обладает встроенной поддержкой для участия в авторизационных потоках OAuth2.0. Он взаимодействует с авторизацией и/или конечными точками токена, как указано в Swagger JSON, чтобы получить токены доступа для последующих вызовов API. См. Добавление определений и требований безопасности для примера добавления метаданных OAuth2.0 к сгенерированному чванству.
Если ваша конечная точка Swagger включает в себя соответствующие метаданные безопасности, взаимодействие пользовательского интерфейса должно быть автоматически включено. Тем не менее, вы можете дополнительно настроить поддержку OAuth в пользовательском интерфейсе со следующими настройками ниже. Смотрите документацию Swagger-UI для получения дополнительной информации:
app.useswaggerui (c => {c.oauthclientid ("test-id"); c.oauthclientsecret ("test-secret"); c.oauthusername ("test-user"); C.OauthRealm («Test-Realm" ); string, string> {{"foo", "bar"}});Чтобы использовать пользовательские перехватчики по запросам и ответам, проходящим через Swagger-UI, вы можете определить их как функции JavaScript в конфигурации:
app.useswaggerui (c => {c.userequestinterceptor ("(req) => {req.headers ['x-my-custom-header'] = 'mycustomvalue'; return req;}"); c.useresponseinterceptor (" (res) => {console.log ('Custom Interceptor Reception Response из:', res.url);Это может быть полезно в различных сценариях, где вы можете добавить локальные токены XSRF ко всем запросам, например:
app.useswaggerui (c => {c.userequestinterceptor ("(req) => {req.headers ['x-xsrf-token'] = localstorage.getitem ('xsrf-token'); return req;}"); });Установите следующий пакет Nuget в свое приложение ASP.NET Core.
Package Manager : Install-Package Swashbuckle.AspNetCore.Annotations CLI : dotnet add package Swashbuckle.AspNetCore.Annotations
В методе ConfigureServices of Startup.cs включите аннотации в блок конфигурации Swagger:
services.addswaggergen (c => {... c.enableannotation ();}); После того, как аннотации были включены, вы можете обогатить сгенерированные метаданные операции, украшая действия с помощью SwaggerOperationAttribute .
[Httppost] [Swaggeroperation (Summary = «Создает новый продукт», description = «Требуется привилегии администратора», OperationId = "createProduct", Tags = new [] {"покупка", "продукты"})] public iActionResult create ([[[] От куба] продукт продукта) ASP.NET Core предоставляет ProducesResponseTypeAttribute для перечисления различных ответов, которые могут быть возвращены действием. Эти атрибуты могут быть объединены с комментариями XML, как описано выше, чтобы включить дружественные к человеку описания с каждым ответом в сгенерированном чванстве. Если вы предпочитаете делать все это с помощью одного атрибута и избежать использования комментариев XML, вы можете вместо этого использовать SwaggerResponseAttribute S:
[Httppost] [SwaggerResponse (201, «Продукт был создан», Typeof (Product))] [SwaggerResponse (400, «Данные о продукте недействительны»)] Общественный iActionResult Create ([From Body] продукт) продукт)
Вы можете аннотировать «Путь», «запрос» или «заголовок», связанные параметры или свойства (то есть, украшенные [FromRoute] , [FromQuery] или [FromHeader] ) с помощью SwaggerParameterAttribute , чтобы обогатить соответствующие метаданные Parameter , которые генерируются Swashbuck:
[Httpget] public iActionResult getProducts ([fromQuery, SwaggerParameter («Ключевые слова поиска», требуется = true)] Строковые ключевые слова)
Вы можете аннотировать связанные параметры или свойства «корпуса» (то есть украшены [FromBody] ) с помощью SwaggerRequestBodyAttribute , чтобы обогатить соответствующие метаданные RequestBody , которые генерируются Swashbuckle:
[Httppost] public iActionResult createProduct ([от Body, SwaggerRequestbody («Полезная нагрузка продукта», требуется = true)] продукт) продукт) Продукт)
Вы можете аннотировать классы или свойства с помощью SwaggerSchemaAttribute , чтобы обогатить соответствующие метаданные Schema , которые генерируются Swashbuckle:
[Swaggerschema (required = new [] {"description"})] product product {[Swaggerschema ("The Product Identifier", readonly = true)] public int id {get; набор; } [Swaggerschema ("Описание продукта")] публичная строка Описание {get; набор; } [Swaggerschema («Дата, которую она была создана», format = "date")] public DateTime DateCreated {get; набор; }} ПРИМЕЧАНИЕ. В Swagger / OpenAPI сериализованные объекты и содержащие свойства представлены в качестве экземпляров Schema , поэтому эта аннотация может быть применена как к классам, так и к свойствам. Также стоит отметить, что «требуемые» свойства указываются как множество имен свойств на схеме верхнего уровня, в отличие от флага на каждом отдельном свойстве.
Пакет SwaggerGen предоставляет несколько точек расширения, включая фильтры схемы (описанные здесь) для настройки всех сгенерированных схем. Тем не менее, могут быть случаи, когда предпочтительнее применять фильтр к конкретной схеме. Например, если вы хотите включить пример для определенного типа в ваш API. Это можно сделать, украшив тип SwaggerSchemaFilterAttribute :
// product.cs [swaggerschemafilter (typeof (productschemafilter))] product product {...} // productschemafilter.cspublic class productschemafilter: ischemafilter {public void Applic ["Id"] = new OpenApiInteger (1), ["description"] = new OpenApistring ("Awesome Product")};}} По умолчанию генератор Swagger будет помечать все операции с именем контроллера. Этот тег затем используется для управления операциями группировки в Swagger-UI. Если вы хотите дать описание для каждой из этих групп, вы можете сделать это, добавив метаданные для каждого тега имени контроллера через SwaggerTagAttribute :
[Swaggertag («Создать, читать, обновить и удалять продукты»)] Public Class ProductsController {...} Примечание. Это добавит вышеуказанное описание специально в тег с именем «Продукты». Поэтому вам следует избегать использования этого атрибута, если вы помечаете операции с чем -то другим, кроме имени контроллера - например, если вы настраиваете поведение с тегом с помощью TagActionsBy .
Если вы хотите использовать поведение Swashbuckle и/или полиморфизм, вы можете использовать аннотации, чтобы явно указывать «известные» подтипы для данного базового типа. Это переоценит функцию селектора по умолчанию, которая выбирает все подтипы в той же сборке, что и базовый тип, и, следовательно, необходимо явно включено при включении аннотаций:
// startup.csservices.addswaggergen (c => {c.enableAnnotations (enableAnnotationsforinheritance: true, enyableannotationsforpolymorphism: true);}); // shape.cs [swaggersubtype (typeof (rectangle)] [Swaggersubepe (typeof (circlef) ] открытый абстрактный класс форма {} Если вы используете аннотации, чтобы явно указать «известные» подтипы для полиморфного базового типа, вы можете объединить SwaggerDiscriminatorAttribute с SwaggerSubTypeAttribute , чтобы предоставить дополнительные метаданные о свойстве «дискриминатор», которое затем будет включено в определение сгенерированной инфекции:
// startup.csservices.addswaggergen (c => {c.enableAnnotations (eNabLeanNotationsforInheritance: True, EnableAnnotationsForpolymorphism: true);}); // shape.cs [SwaggerDiscriminator ("ShapeType")] [SwaggerSubUb = "прямоугольник")] [swaggersubtype (typeof (circle), discinatorValue = "circle")] открытый абстрактный класс форма {public shapeType {get; набор; }} Это указывает на то, что соответствующая полезная нагрузка будет иметь свойство «Shapetype» для различения между подтипами, и это свойство будет иметь значение «прямоугольник», если полезная нагрузка представляет собой тип Rectangle и значение «круга», если оно представляет собой тип Circle . Эта деталь будет описана в определении схемы схемы следующим образом:
schema: {
oneOf: [
{
$ref: "#/components/schemas/Rectangle"
},
{
$ref: "#/components/schemas/Circle"
},
],
discriminator: {
propertyName: shapeType,
mapping: {
rectangle: "#/components/schemas/Rectangle",
circle: "#/components/schemas/Circle",
}
}
}После того, как ваше приложение будет настроено на Swashbuckle (см. Начало работы), вы можете использовать инструмент CLI Swashbuckle для извлечения Swagger / OpenApi JSON непосредственно из запуска вашего приложения и написать его в файл. Это может быть полезно, если вы хотите включить генерацию Swagger в процесс CI/CD, или если вы хотите обслуживать его из статического файла во время выполнения.
Он упакован как инструмент .net, который можно установить и использовать через Dotnet SDK.
️ Инструмент должен загрузить ваш стартап DLL и его зависимости во время выполнения. Поэтому вам следует использовать версиюdotnetSDK, которая совместима с вашим приложением. Например, если ваше приложение предназначено дляnet6.0, то вам следует использовать версию 6.0.xxx SDK для запуска инструмента CLI. Если он предназначен дляnet8.0, то вам следует использовать версию 8.0.xxx SDK и так далее.
Установить как глобальный инструмент
dotnet tool install -g Swashbuckle.AspNetCore.Cli
Убедитесь, что инструмент был установлен правильно
swagger tofile --help
Создайте документ Swagger/ OpenAPI из запуска вашего приложения
swagger tofile --output [output] [startupassembly] [swaggerdoc]
Где ...
[Вывод] - это относительный путь, в котором Swagger JSON будет выводить на
[Startupassembly] - это относительный путь к сборке запуска вашего приложения
[Swaggerdoc] - это название документа Swagger, который вы хотите получить, как настроено в вашем классе запуска
В корне проекта создайте файл манифеста инструмента:
dotnet new tool-manifest
Установить как локальный инструмент
dotnet tool install Swashbuckle.AspNetCore.Cli
Убедитесь, что инструмент был установлен правильно
dotnet swagger tofile --help
Создайте документ Swagger / OpenAPI из запуска вашего приложения
dotnet swagger tofile --output [output] [startupassembly] [swaggerdoc]
Где ...
[Вывод] - это относительный путь, в котором Swagger JSON будет выводить на
[Startupassembly] - это относительный путь к сборке запуска вашего приложения
[Swaggerdoc] - это название документа Swagger, который вы хотите получить, как настроено в вашем классе запуска
За пределами ящика инструмент будет выполняться в контексте веб-хоста «по умолчанию». Тем не менее, в некоторых случаях вы можете принести свою собственную среду хоста, например, если вы настроили пользовательский контейнер DI, такой как AutoFac. Для этого сценария инструмент Swashbuckle CLI открывает конференц-крючок для вашего приложения.
То есть, если ваше приложение содержит класс, который соответствует любым из следующих соглашений об именах, то этот класс будет использоваться для предоставления хоста для инструмента CLI для работы.
public class SwaggerHostFactory , содержащий публичный статический метод, называемый CreateHost с возвратом типа IHost
public class SwaggerWebHostFactory , содержащий публичный статический метод, называемый CreateWebHost с возвратом типа IWebHost
Например, следующий класс может быть использован для использования той же конфигурации хоста, что и ваше приложение:
открытый класс SwaggerHostFactory {public static ihost createhost () {return Program.createHostBuilder (new String [0]). Build ();}}По умолчанию пользовательский интерфейс REDOC будет выставлен в "/API-DOCS". При необходимости вы можете изменить это при включении промежуточного программного обеспечения REDOC:
app.useredoc (c => {c.routeprefix = "docs" ...}По умолчанию пользовательский интерфейс REDOC будет иметь общий заголовок документа. Вы можете изменить это при включении промежуточного программного обеспечения Redoc:
app.useredoc (c => {c.documenttitle = "my api docs"; ...}Redoc поставляется со своим собственным набором параметров конфигурации, все описаны здесь https://github.com/rebilly/redoc/blob/main/readme.md#redoc-options-object. В Swashbuckle большинство из них всплывают через варианты промежуточного программного обеспечения Redoc:
app.useredoc (c => {c.specurl ("/v1/swagger.json"); c.enableuntrustedspec (); c.scrollyoffset (10); c.hidehostname (); c.hadhadownloadbutton (); c.expandresponses (200,201); SortPropsAlphaboty ();}); Использование c.SpecUrl("/v1/swagger.json") несколько раз в одном и том же UseReDoc(...) не будет добавлять несколько URL -адресов.
Чтобы настроить внешний вид, вы можете ввести дополнительные таблицы стилей CSS, добавив их в свою папку wwwroot и указав относительные пути в параметрах промежуточного программного обеспечения:
app.useredoc (c => {... c.injectstylesheet ("/redoc/custom.css");} Также можно изменить тему, используя свойство AdditionalItems , см. Https://github.com/rebilly/redoc/blob/main/readme.md#redoc-options-object для получения дополнительной информации.
app.useredoc (c => {... c.configobject.additionalitems = ...}Чтобы настроить пользовательский интерфейс помимо основных вариантов, перечисленных выше, вы можете предоставить собственную версию страницы Redoc Index.html:
app.useredoc (c => {c.indexstream = () => getType (). Assembly .getManifestresourcestream ("CustomIndex.redoc.index.html"); // Требуется добавить файл в виде встроенного ресурса});Чтобы начать, вы должны основывать свой пользовательский index.html на версии по умолчанию
