Swashbuckle.AspNetCore

重要的通知，如果您在主要版本之间升级！
*如果您将4.x升级到5.x，则需要了解几种破裂的更改。有关详细信息，请参见发行说明 *如果您首先从3.x跳到4.x，那里也有龙。在这里查看这些发行说明

swashbuckle.aspnetcore

使用ASP.NET Core构建的API的Swagger Tooling。直接从您的路线，控制器和模型中生成精美的API文档，包括用于探索和测试操作的UI。

除了Swagger 2.0和OpenAPI 3.0发电机外，Swashbuckle还提供了由生成的Swagger Json提供动力的Awesome Swagger-UI的嵌入式版本。这意味着您可以与始终与最新代码同步的生活文档相辅相成。最重要的是，它需要最少的编码和维护，使您可以专注于构建出色的API。

那不是全部...

一旦拥有可以用夸张描述自己的API，您就可以打开基于夸张的工具的宝藏，包括可以针对广泛流行平台的客户生成器。有关更多详细信息，请参见Swagger-Codegen。

兼容性

swashbuckle版本	ASP.NET核心	Swagger / OpenAPI规格。	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

入门

1. 将标准Nuget软件包安装到您的ASP.NET核心应用程序中。

   Package Manager : Install-Package Swashbuckle.AspNetCore
   CLI : dotnet add package Swashbuckle.AspNetCore

2. 在Startup.cs的ConfigureServices方法中，注册Swagger Generator，定义一个或多个Swagger文档。

   使用microsoft.openapi.models;

    services.addmvc（）; services.AddSwaggerGen（C => {C.SwaggerDoc（“ V1”，新的OpenApiInfo {title =“ my api”，version =“ v1”}）;}）;}）;

3. 确保您的API动作和参数用明确的“ HTTP”和“来自”绑定装饰。

    [httppost]公共空白createproduct（[[来自Body]产品产品）...

    [httpget] public iEnumerable <product> searchproducts（[frofquery]字符串关键字）...

   注意：如果省略显式参数绑定，则默认情况下，生成器将它们描述为“查询”参数。

4. 在Configure方法中，您应该通过以下方法之一将生成的摇动作为JSON端点：

    app.mapendpoints（endpoints => {// ... endpoints.mapswagger（）;}）;

    app.useswagger（）;

   此时，您可以旋转应用程序，并在“/swagger/v1/swagger.json”上查看生成的Swagger Json。

• 插入中间件

• 如果您使用的是基于端点的路由，请添加端点。

5. 可选地，如果要揭示交互式文档，请插入Swagger-UI中间件，并指定Swagger JSON Endpoint（S）向其供电。

    app.useswaggerui（c => {c.swaggerendpoint（“ v1/swagger.json”，“我的api v1”）;}）;

   现在，您可以重新启动应用程序，并在“/Swagger”中查看自动生成的交互式文档。

system.text.json（STJ）vs newtonsoft

在5.0.0之前的版本中，SwashBuckle将根据NewtonSoft Serialializer的行为生成模式（由API展示的数据类型的描述）。这是有道理的，因为那是当时用ASP.NET核心运送的序列化器。但是，由于版本3.0.0 ，ASP.NET Core引入了新的Serializer System.Text.json（STJ）开箱即用，如果您想继续使用Newtonsoft ，则需要安装单独的软件包并明确地安装选择加入。使用Swashbuckle 5.0.0及以后的模式。也就是说，开箱即用的swashbuckle将假定您使用的是STJ序列化器，并根据其行为生成模式。如果您使用的是Newtonsoft ，则需要安装单独的Swashbuckle软件包并明确选择加入。无论您使用哪种版本的ASP.NET核心，这都是必需的步骤。

总之 ...

如果您使用的是System.Text.json（STJ） ，则上述设置将足够， STJ选项/属性将被Swagger Generator自动尊重。

如果您使用的是Newtonsoft ，则需要安装单独的软件包并明确选择加入，以确保Swagger Generator自动尊重NewtonSoft设置/属性：

Package Manager : Install-Package Swashbuckle.AspNetCore.Newtonsoft
CLI : dotnet add package Swashbuckle.AspNetCore.Newtonsoft

 services.Addmvc（）; services.AddSwaggerGer（C => {C.SwaggerDoc（“ V1”，新的OpenApiInfo {title =“ my api”，version =“ v1”}）; services.addswaggergnewtswaggergnewtonsoftsoftsoftsoftsoftsupport（）; //明确选择 - 需要在AddSwaggergen（）之后放置

swashbuckle，apiexplorer和路由

Swashbuckle在很大程度上依赖于ApiExplorer ，Apiexplorer是API元数据层，该层带有ASP.NET核心。如果您使用AddMvc助手来引导MVC堆栈，则将自动注册APIEXPLORER，并且SB将无问题​​。但是，如果您使用AddMvcCore进行更多配对的MVC堆栈，则需要明确添加ApieXplorer服务：

 services.addmvccore（）。addapiexplorer（）;

此外，如果您使用的是常规路由（与属性路由相反），则在Apiexplorer中不会表示任何控制器和使用常规路由的控制器的操作，这意味着Swashbuckle将无法找到这些控制器并生成Swagger他们的操作。例如：

 app.usemvc（routes => {// Swaggergen找不到通过此技术路由的控制器。ROUTES.MAPROUTE（“ default”，“ {controller = home}/{action}/{action = index}/{idex}/{id？}”） ;}）;

您必须使用Swagger文档中所需的任何控制器使用属性路由：

 [ROUTE（“示例”）] public Class esupplecontroller：Controller {[httpget（“”）] public iCultionResult dostuff（）{ / ** /}}

有关更多信息，请参阅路由文档。

成分

Swashbuckle由多个组件组成，可以根据您的需求一起使用或单独使用。从本质上讲，有一个摇摇欲坠的发电机，中间件将其暴露为JSON端点，以及包装的Swagger-UI版本。这3个软件包可以使用Swashbuckle.AspNetCore “ metapackage”安装，并将无缝合作（请参阅入门），以提供从您的代码自动生成的精美API文档。

此外，还有附加软件包（CLI工具，备用UI等），您可以根据需要选择安装和配置。

“核心”软件包（即通过swashbuckle.aspnetcore安装）

包裹	描述
swashbuckle.aspnetcore.swagger	露出大肆宣传JSON端点。它预计将在DI容器中注册ISwaggerProvider的实现，并查询检索OpenAPIDocument(s)然后将其暴露为序列化的JSON
swashbuckle.aspnetcore.swaggergen	注入以上组件可以使用的ISwaggerProvider的实现。该特定实现从您的路线，控制器和模型生成OpenApiDocument(s)
swashbuckle.aspnetcore.swaggerui	暴露了Swagger-UI的嵌入式版本。您指定可以获得Swagger JSON的API端点，并使用它们为您的API供电

其他软件包

包裹	描述
swashbuckle.aspnetcore.annotations	包括一组可以应用于控制器，操作和模型以丰富生成的招摇的自定义属性
swashbuckle.aspnetcore.cli	提供了一个命令行接口，用于直接从启动组件中检索Swagger，然后写入文件
swashbuckle.aspnetcore.redoc	暴露了REDOC UI的嵌入式版本（Swagger-UI的替代品）

社区套餐

这些软件包由开源社区提供。

包裹	描述
swashbuckle.aspnetcore.filters	一些有用的Swashbuckle过滤器，这些过滤器添加了其他文档，例如请求和响应示例，授权信息等。有关更多详细信息，请参见其README
unchase.swashbuckle.aspnetcore.extensions	一些有用的扩展名（过滤器），这些扩展（过滤器）添加了其他文档，例如，为未知的角色隐藏patiTems，修复了客户代码生成的枚举等。有关更多详细信息，请参见其读数。
微元素	使用FulentValidation规则，而不是ComponentModel属性来增强生成的Swagger Schemas
mmlib.swaggerforocelot	直接在Ocelot API网关上的微服务的汇总文档

配置和自定义

上述步骤将使您启动并以最少的设置运行。但是，Swashbuckle提供了很多灵活性来自定义，这是您所觉得合适的。查看下表以获取选项的完整列表：

• swashbuckle.aspnetcore.swagger

• 改变Swagger JSON端点的道路

• 通过请求上下文修改Swagger

• 以2.0格式序列化摇摇JSON

• 使用虚拟目录和反向代理

• 自定义OpenAPI文档如何序列化

• swashbuckle.aspnetcore.swaggergen

• 分配显式操作ID

• 列表操作响应

• 标志所需的参数和模式属性

• 处理表格和文件上传

• 处理文件下载

• 包括XML评论中的描述

• 提供全球API元数据

• 生成多个招摇文件

• 省略过时的操作和/或模式属性

• 省略任意操作

• 自定义操作标签（例如，UI分组）

• 更改操作排序顺序（例如，UI排序）

• 自定义模式ID

• 特定类型的覆盖模式

• 使用操作，模式和文档过滤器扩展发电机

• 添加安全定义和要求

• 添加载体Auth的安全定义和要求

• 继承和多态性

• swashbuckle.aspnetcore.swaggerui

• 将相对路径更改为UI

• 更改文档标题

• 更改CSS或JS路径

• 列出多个宣传文件

• 应用Swagger-UI参数

• 注入自定义JavaScript

• 注入自定义CSS

• 自定义index.html

• 启用oauth2.0流

• 使用客户端请求和响应拦截器

• swashbuckle.aspnetcore.annotations

• 安装和启用注释

• 富集操作元数据

• 丰富响应元数据

• 丰富参数元数据

• 丰富请求boby元数据

• 富集模式元数据

• 将模式过滤器应用于特定类型

• 添加标签元数据

• swashbuckle.aspnetcore.cli

• 直接从初创企业组装中取出Swagger

• 使用具有自定义主机配置的CLI工具

• swashbuckle.aspnetcore.redoc

• 将相对路径更改为UI

• 更改文档标题

• 应用重复参数

• 注入自定义CSS

• 自定义index.html

swashbuckle.aspnetcore.swagger

改变Swagger JSON端点的道路

默认情况下，Swagger Json将在以下路线上暴露 -“/swagger/ {documentName }/swagger.json”。如有必要，您可以在启用Swagger中间件时更改此操作。自定义路由必须包括{documentName}参数。

 app.useswagger（c => {c.routetemplate =“ api-docs/{documenname}/swagger.json”;}）

注意：如果您使用的是Swaggerui中间件，则还需要更新其配置以反映新的端点：

 app.useswaggerui（c => {c.swaggerendpoint（“/api-docs/v1/swagger.json”，“我的api v1”）;}）

注意：如果您还需要更新UI本身可用的相对路径，则需要遵循在变更中发现的UI相对路径中发现的说明。

通过请求上下文修改Swagger

如果您需要根据当前请求设置一些Swagger Metadata，则可以配置在序列化文档之前执行的过滤器。

 app.useswagger（c => {c.preserializefilters.add（（（Swagger，httpReq）=> {Swagger.Servers =新列表<OpenApiserver> {new OpenApiserver {new OpenApiserver {url = $ {url = $“ {httpreq.scheme}：// host.value}“}};}）;}）;

OpenApiDocument和当前的HttpRequest都将其传递给过滤器。这提供了很大的灵活性。例如，您可以根据“主机”标头添加明确的API服务器（如图所示），也可以检查会话信息或授权标题，并根据用户权限从文档中删除操作。

以2.0格式序列化Swagger

默认情况下，SwashBuckle将在规范的3.0版中生成和揭露Swagger JSON，正式称为OpenAPI规范。但是，为了支持向后兼容性，您可以选择以2.0格式将其曝光，并具有以下选项：

 app.useswagger（c => {c.serializeasv2 = true;}）;

使用虚拟目录和反向代理

虚拟目录和反向代理可能会引起生成链接和重定向的应用程序的问题，尤其是当应用程序根据Host标头返回绝对URL以及从当前请求返回其他信息时。为了避免这些问题，Swashbuckle在可能的情况下使用相对URL，并在配置Swaggerui和Redoc中间件时鼓励使用它们。

例如，要连接Swaggerui中间件，您将URL提供给一个或多个OpenAPI/Swagger文档。这是客户端应用程序Swagger-UI将呼吁检索API元数据的URL。为了确保虚拟目录和反向代理背后的作用，您应该相对于Swagger-UI本身的RoutePrefix表达这一点：

 app.useswaggerui（c => {c.RoutepRefix =“ Swagger”; c.swaggerendpoint（“ v1/swagger.json”，“我的api v1”）;}）;}）;

注意：在文档的先前版本中，您可能已经将其表示为词根相关链接（例如/swagger/v1/swagger.json ）。如果您的应用程序托管在IIS虚拟目录上或在转发前修剪请求路径的代理后面，则该应用程序将不起作用。如果切换到上面显示的页面相关语法，则在所有情况下都应使用。

自定义OpenAPI文档如何序列化

默认情况下，SwashBuckle将使用OpenAPI文档对象上的序列化方法序列化OpenAPI文档。如果需要定制的序列化，则可以创建一个实现ISwaggerDocumentSerializer接口的自定义文档序列化器。可以使用ConfigureSwagger()在服务集合中的SwaggerOptions上设置这一点：

笔记

如果您打算使用命令行工具生成OpenAPI规范文件，则必须在Service Collection上使用ConfigureSwagger()完成此操作。

 services.configureswagger（options => {option.setCustomDocumentserizer <customDocumentsErializer>（）;}）

当不使用命令行工具时，也可以在应用程序主机上完成：

 app.useswagger（options => {options.setCustomDocumentserizer <customDocumentserializer>（）;}）

swashbuckle.aspnetcore.swaggergen

分配显式操作ID

摇摇欲坠，可以将操作分配一个operationId 。此ID必须在API中描述的所有操作中是唯一的。工具和库（例如客户端生成器）可以使用操作ID唯一识别操作，因此，建议遵循常见的编程命名约定。

自动生成与这些要求匹配的ID，同时还提供了在客户端库中有意义的名称是一项非平凡的任务，因此，Swashbuckle默认情况下省略了operationId 。但是，如有必要，您可以通过装饰单个路线或提供自定义策略来分配operationIds 。

选项1）用Name属性装饰路线

[httpget（“ {id}”，name =“ getProductById”）] public iCultionResult get（int ID）// aperationid =“ getProductById”

选项2）提供自定义策略

// startup.csservices.addswaggergen（c => {... //使用方法名称为aperationId c.customoperations（apidesc => {return apidesc.trygetc.trygetmethodinfo（out methodInfo methodInfo）？methodinfo）？methodinfo.name：name：null;}）;}）;}）;};}） ）// productscontroller.cs [httpget（“ {id}”）] public iNuctionResult getProductById（int ID）// aperationid =“ 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}”）]

将产生以下响应元数据：

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将自动将其标记为生成的Swagger中的“必需”参数：

 // productsController.cspublic iictionResult搜索（[FromQuery，BindRequired]字符串关键字，[FromQuery] PagingParams pagingParams）{if（！modelState.isvalid） ] public int pageno {get;放; } public int pagesize {get;放; }}}

除了参数外，Swashbuckle还将在与请求主体绑定的模型中使用时RequiredAttribute工作。在这种情况下，装饰的属性将被标记为身体描述中的“必需”属性：

 // productscontroller.cspublic iRinctionResult create（[来自Body]产品产品）{if（！modelState.isvalid）返回badrequest（modelState）; ...} // product.cspublic class class products {[[必需] public string string name {放; }公共字符串描述{get;放; }}}

处理表格和文件上传

该控制器将接受两个表单字段值和一个从同一表单上传的命名文件：

 [httppost] public void uploadfile（[来自form]字符串描述，[fromform] dateTime客户端，iformfile文件）

重要说明：根据ASP.NET核心文档，您不应该用[FromForm]属性来装饰IFormFile参数，因为从类型中自动推断出绑定源。实际上，推断的值是BindingSource.FormFile ，如果应用属性，它将设置为BindingSource.Form ，而代替，它拧紧ApiExplorer ，apiexplorer，apiexplorer，apiexplorer，apiexplorer，apiexplorer，它具有asp.net core的元数据，并由swashbuckle依靠。这里的一个特殊问题是Swaggerui不会将参数视为文件，因此，如果您错误地包含此属性，则不会显示文件上传按钮。

处理文件下载

ApiExplorer （SwashBuckle所建立的ASP.NET核心元数据组件）不会默认地呈现FileResult类型，因此您需要用ProducesResponseType属性（或在.NET 5或.NET 5或以上Produces ）中明确说明它。

 [httpget（“ {filename}”）] [productesResponSeType（typeof（fileStreamResult），statuscodes.status200ok，“ image/jpeg”）] public filestreamresult getfile（String fileName）

包括XML评论中的描述

为了增强具有人类友好描述的生成的文档，您可以用XML注释注释控制器操作和模型，并配置SwashBuckle，将这些注释纳入输出的Swagger JSON：

1. 打开项目的“属性”对话框，单击“构建”选项卡，并确保检查“ XML文档文件”，或将<GenerateDocumentationFile>true</GenerateDocumentationFile> element添加到.csproj项目文件的<PropertyGroup> electer。这将产生一个包含所有XML注释的文件。

   此时，未用XML注释注释的任何类或方法都会触发构建警告。为了抑制这一点，请在“属性对话框”中的“抑制警告”字段中输入警告代码“ 1591”，或在.csproj项目文件的<PropertyGroup>部分中添加<NoWarn>1591</NoWarn> 。

2. 配置swashbuckle以将文件中的XML注释纳入生成的Swagger JSON：

    services.AddSwaggergen（C => {C.SwaggerDoc（“ V1”，新的OpenApiInfo {title =“ My Api -V1”，version =“ v1”}）; c.includexmlcomments（assembly.getExeceCutingAssembly（） c.includexmlComments（typeof（myController）.sembly））;}

3. 用摘要，备注，参数和响应标签注释您的动作：

    /// <summary> ///通过唯一ID /// </summary> /// <earlds> awesomeness！</reverns> /// <param name =“ id>“ id” example =“ 123”）检索特定产品>产品ID </param> /// <响应代码=“ 200”>检索的产品</wesponse> // <响应代码=“ 404”>找不到</wessions> /// <响应代码= “ 500”>糟糕！无法立即查找您的产品</wession> [httpget（“ {id}”）] ID）

4. 您还可以用摘要和示例标签注释类型：

   公共类产品{/// <summary> ///产品的名称/// </summary> /// <example>男士篮球鞋</example> public string name {get;放; } /// <summary> ///库存中留下的数量/// </summary> /// <example> 10 </xpulent> public int int availablestock {get;放; } /// <summary> ///尺寸该产品可在/// </summary> /// <example>> [“ SMALL”，“ MEDID”，“大型”] </example>公共列表<字符串>尺寸{get;放; }}}

5. 重建您的项目以更新XML注释文件并导航到Swagger JSON端点。注意如何将描述映射到相应的宣传场。

注意：您还可以通过用摘要标签注释API模型及其属性来提供Swagger模式描述。如果您有多个XML注释文件（例如，用于控制器和模型的单独库），则可以多次调用IncludexmlComments方法，它们都将合并到输出的Swagger JSON中。

提供全球API元数据

除了为您生成的“ Pathitems”，“操作”和“响应”外，Swagger还支持全局元数据（请参阅https://swagger.io/specification/#oasobject）。例如，您可以为您的API，服务条款甚至联系和许可信息提供完整的描述：

 c.swaggerdoc（“ v1”，新的OpenApiInfo {title =“ my api -v1”，version =“ v1”，description =“示例api to demo swashbuckle”，enterofservice = new uri（“ http：//tempuri.org） /enter“），contact = new OpenApiconTact {name =“ Joe Developer”，email =“ [email protected]”}，许可证= new OpenApilicense {new openapilicense {name =“ apache 2.0”，url = url = new uri（“ https：” https：“ https：” //www.apache.org/licenses/license-2.0.html“）}}）;

提示：使用IntelliSense查看其他哪些字段。

生成多个招摇文件

通过上述设置，生成器将在单个Swagger文档中包含所有API操作。但是，如有必要，您可以创建多个文档。例如，您可能需要为API的每个版本提供一个单独的文档。为此，首先在Startup.cs中定义多个Swagger文档：

 services.AddSwaggergen（C => {C.SwaggerDoc（“ V1”，New OpenApiInfo {title =“ My api -v1”，版本=“ v1”}）; c.swaggerdoc（“ v2”，new OpenApiInfo {new Openapiinfo {title =“我的API -V2“，版本=“ V2”}）;}）

请注意Swaggerdoc的第一个论点。它必须是一个对URI友好的名称，可以独特地识别该文档。随后，它用来构成请求相应的Swagger JSON的路径。例如，使用默认路由，上述文档将在“/swagger/v1/swagger.json”和“/swagger/v2/swagger.json”上找到。

接下来，您需要通知每个文档中要包含哪些操作。尽管可以自定义（请参见下文），但默认情况下，生成器将使用ApiDescription.GroupName属性，该属性是用ASP.NET核心运输的内置元数据层的一部分，以进行此区别。您可以通过装饰单个动作或应用广泛的惯例来设置此设置。

装饰个人行动

要在特定的Swagger文档中包含一个操作，请使用ApiExplorerSettingsAttribute进行装饰，然后将GroupName设置为相应的文档名称（案例敏感）：

 [httppost] [apiexplorersettings（groupName =“ v2”）]公共void post（[来自Body]产品产品）

通过公约将诉讼分配给文档

要通过惯例进行分组而不是装饰所有动作，您可以应用自定义控制器或动作惯例。例如，您可以根据控制器名称空间将以下约定汇合以将操作分配给文档。

 // apiexplorergrouperverversionconconconvention.cspublic类apiexplorergrouperververversionconvention：icontrollerModeLconvention {public void apply（controllerModel Controller）{var contrancterNamespace = controller.controllerTyper.controllerType.namespace; //例如“ controlrers.v1” var apiversion = ControllerNamespace.split（'。'）。last（）。tolower（）; controller.apiexplorer.groupname = apiversion = apivers;}}}} // startup.cspubl.cspublic void void configureservices（iserviceCollection services）{ services.Addmvc（c => c.conventions.Add（new ApiexplorerGrouperverversionConconcention（）））; ...}

自定义动作选择过程

当选择给定的Swagger文档的动作时，生成器会针对框架浮出水面的每个ApiDescription调用DocInclusionPredicate 。默认实现检查ApiDescription.GroupName ，如果值为null或等于所请求的文档名称，则返回true。但是，您还可以提供自定义的包容性谓词。例如，如果您使用基于属性的方法来实现API版本（例如Microsoft.aspnetcore.mvc.versioning），则可以配置一个自定义谓词，该自定义谓词会利用版本化属性：

 c.docinclusionPredicate（（（DocName，apidesc）=> {if（！Apidesc.trygetMethodInfo（Out MethodInfo MethodInfo））返回false; var versions = methodInfo.declaringType.getCustomatTomatTributes（true） > attr.versions）;

通过UI暴露多个文档

如果您使用的是SwaggerUI中间件，则需要指定要曝光的任何其他Swagger端点。有关更多信息，请参见列表多个Swagger文档。

省略过时的操作和/或模式属性

Swagger规格包括一个deprecated标志，以表明操作被弃用，并应避免使用。如果相应的操作用ObsoleteAttribute装饰，则Swagger Generator将自动设置此标志。但是，您可以配置发电机以完全忽略过时的操作，而不是设置标志：

 services.addswaggergen（c => {... c.ignoreobsoleteactions（）;};

也可以使用类似的方法来省略Swagger输出中模式的过时性能。也就是说，您可以使用ObsoleteAttribute装饰模型属性，并配置swashbuckle，以省略这些属性，以生成JSON Schemas：

 services.AddSwaggerGen（c => {... c.ignoreObsoleteProperties（）;};

省略任意操作

您可以通过装饰单个动作或应用广泛的约定来省略Swagger输出的操作。

装饰个人行动

要省略特定的动作，请用ApiExplorerSettingsAttribute进行装饰，并设置IgnoreApi标志：

 [httpget（“ {id}”）] [apiexplorersettings（ignoreapi = true）]公共产品getByid（int id）

省略公约行动

为了通过惯例省略行动，而不是单独装饰它们，您可以应用自定义行动惯例。例如，您可以将以下约定汇总以获取操作：

 // apiexplorergetsonlyconvention.cspublic类apiexplorergetSonlyConcention：iictionModelConcention {public void applion（actionModel action）{action.apiexplorer.isvisible = action = action = action = action.attributes.attributes.oftype <httppetTribute issect in. outrection services）{services.addmvc（c => c.conventions.add（new ApiexplorergetSonlyConcention（）））; ...}

自定义操作标签（例如，UI分组）

Swagger Spec允许将一个或多个“标签”分配给操作。 Swagger Generator将把控制器名称分配为默认标签。这很重要，需要注意，如果您使用SwaggerUI中间件，因为它将此值用于组操作。

您可以通过提供按照惯例应用标签的函数来覆盖默认标签。例如，以下配置将通过HTTP方法标记，因此在UI中进行了组操作：

 services.AddSwaggergen（c => {... c.tagactionsby（api => api.httpmethod）;};};

更改操作排序顺序（例如，UI排序）

默认情况下，通过分配的标签（请参见上文）排序操作，然后将其分组为以路径为中心的Swagger Spec的嵌套结构。但是，您可以通过自定义排序策略更改操作的默认排序：

 services.AddSwaggergen（c => {... c.orderactionsby（（（apidesc）=> $” {apidesc.actiondescriptor.routevalues [“ controler”]} _ {apidesc.httpmethod} _} _};};};

注意：这决定了在将动作分组并转换为夸张格式之前的排序顺序。因此，它会影响组的顺序（即Swagger“ pathitems”），以及在招摇输出中的组中的操作排序。

自定义模式ID

如果生成器遇到复杂的参数或响应类型，它将生成相应的JSON模式，将其添加到全局components/schemas词典中，并通过唯一ID从操作描述中引用它。例如，如果您有返回Product类型的操作，则生成的模式将如下所述：

responses: {
  200: {
    description: "OK",
    content: {
      "application/json": {
        schema: {
          $ref: "#/components/schemas/Product"
        }
      }
    }
  }
}

但是，如果它遇到具有相同名称的多种类型，但是不同的名称空间（例如RequestModels.Product ＆ ResponseModels.Product ），则Swashbuckle将由于“矛盾的schemaids”而引起例外。在这种情况下，您需要提供一种自定义ID策略，该策略进一步符合名称：

 services.addswaggergen（c => {... c.customschemaids（（type）=> type.fullname）;};};

有关嵌套类型的支持，请参见＃2703。

特定类型的覆盖模式

开箱即用，Swashbuckle在生成JSON模式方面做得不错，可以准确描述您的请求和响应有效负载。但是，如果您要自定义API中某些类型的序列化行为，则可能需要帮助它。

例如，您可能有一个具有多个属性的类，您想在JSON中表示为逗号分隔的字符串。为此，您可能会实现自定义JsonConverter 。在这种情况下，Swashbuckle不知道如何实现转换器，因此您需要为其提供准确描述类型的模式：

 // phonenumber.cspublic类PhoneNumber {public String CountryCode {get;放; } public String airscode {get;放; } public String subscriberid {get;放; }} // startup.csservices.addswaggergen（c => {... c.maptype <Phonenumber>（（）=> new OpenApeChema {type =“ strign” strign'}）;};};

使用操作，模式和文档过滤器扩展发电机

Swashbuckle暴露了一条过滤管道，该管道将挂钩到生成过程中。产生后，单个元数据对象将传递到管道中，可以进一步修改它们。您可以连接自定义过滤器，以丰富生成的“操作”，“架构”和“文档”。

操作过滤器

SwashBuckle检索每个动作的ASP.NET Core的一部分的ApiDescription ，并使用它来生成相应的OpenApiOperation 。生成后，它通过配置的操作过滤器列表将OpenApiOperation和ApiDescription传递。

在典型的过滤器实现中，您将检查ApiDescription是否相关信息（例如路由信息，操作属性等），然后相应地更新OpenApiOperation 。例如，以下过滤器列出了所有用AuthorizeAttribute的动作的额外的“ 401”响应：

 // authResponsOperationFilter.cspublic类AuthRessesoperationFilter：ioperationFilter {public void apply（OpenApioperation操作，FiperfilterContext Context）{var authattributes = <osterizeattribute >（）; if（authattributes.any（））uperation.responses.add（“ 401”，new OpenApiResponse {description =“未授权”}}}}}}} // startup.csservices.csservices.addswagger（c => {... {... {... C.OperationFilter <AuthResseSoperationFilter>（）;};

注意：过滤管道是Di-Wearw的。也就是说，您可以使用构造函数参数创建过滤器，如果参数类型已在DI框架中注册，则将在实例化过滤器时自动注入它们

模式过滤器

Swashbuckle为您的控制器操作所暴露的每个参数，响应和属性类型生成了夸张的jsonschema。生成后，它将传递架构并通过配置的模式过滤器列表进行输入。

下面的示例添加了一个自动供应商扩展名（请参阅https://github.com/azure/autorest/blob/master/master/docs/extensions/extensions/readme.md#x-ms-enum），以告知自动工具如何枚举枚举当它生成API客户端时。

 // autorestschemafilter.cspublic类Autorestschemafilter：Ischemafilter {public void Applion（OpenApisChema Schema，schemafiltercontext context）{var type = context.contest.type; if（type.isenum） OpenApiObject {[[“ name”] = new OpenApistring（type.name），[“ modelAsstring”] = new OpenApiBoolean（true）}）;}}}}};}};} 。

下面的示例允许自动架构生成通用Dictionary<Enum, TValue>对象。请注意，这只会产生招摇。 System.Text.Json默认情况下无法解析词典枚举，因此您需要一个特殊的jsonConverter，例如.NET DOCS中

// dictionarytkeyenumtvalueschemafilter.cspublic类词Yarytkeyenumtvalueschemafilter：Ischemafilter {
  公共空白应用（OpenApischema架构，schemafiltercontext上下文）
  {//仅用于字典<enum，tvalue> if（！context.type.isgenerictype ||！！ var keytype = context.type.getGenericArguments（）[0]; var valueType = context.type.getGenericArguments（）[1] [1]; if（！keykeytype.isenum）{return;} schema.type =“ object”; schema.properties; schema.properties; schema.properties; = keytype.getEnumnames（）。
  }}} // startup.csservices.addswaggergen（c => {... //这些将由dictionarytkeyenumtvalueschemchemafilter替换，但是需要避免错误。///////////////// 。

文档过滤器

一旦生成了OpenApiDocument ，也可以通过一组预配置的文档过滤器将其传递。这可以完全控制以修改文档，但是您认为合适。为了确保您仍在返回有效的Swagger JSON，在使用此过滤器类型之前，应该读取规范。

下面的示例为分配给文档中运行的所有标签提供了描述：

公共类TagDescriptionsdocumentFilter：idocumentFilter {public void apply（openapidocument swaggerdoc，documentFilterContext上下文）{swaggerdoc.tags = new List <openapitag> {new OpenApitag> {new OpenApitag {new OpenApitag {new OpenApitag {new openapitag {name =“ name =” product {name =“ orders”，description =“提交订单”}};}}}}

注意：如果您使用的是SwaggerUI中间件，则可以使用上面演示的TagDescriptionsDocumentFilter来显示每个操作旁边的其他说明。

添加安全定义和要求

在Swagger中，您可以通过定义一个或多个安全方案（例如基本API密钥，OAUTH2等）来描述API的确保，并声明这些方案中的哪些方案适用于全球或特定操作。有关更多详细信息，请查看Swagger Spec中的安全要求对象。

在swashbuckle中，您可以通过调用AddSecurityDefinition方法来定义方案，提供OpenApiSecurityScheme的名称和实例。例如，您可以定义OAuth 2.0-隐式流量如下：

 // startup.csservices.addswaggergen（c => {... //定义正在使用的OAuth2.0方案（即隐式流）C.AddSecurityDefinition（“ oauth2”，new OpenApiseCuritySchemeSchemeScheme新的OpenApioAuthflows {nragit = new OpenApioAuthflow {pretarizationurl = new Uri（“/auth-server/connect/openerize”，urikind.relative），scopes = new Dictionary <string，string，string> {{{{“ readaCcess”，readaCcess“，” ，{“ WriteAccess”，“访问写操作”}}}}}}};};};};

注意：除了定义方案外，您还需要指出该方案适用的操作。您可以通过AddSecurityRequirement方法在全球应用计划（即所有操作）。下面的示例表明，应将称为“ OAuth2”的方案应用于所有操作，并且需要“ ReadAccess”和“ WriteAccess”范围。在应用“ OAuth2”以外的其他类型方案时，范围的数组必须为空。

 c.Addswaggergen（C => {... c.AddseCurityRequirement（新的OpenApiseCurityRequirement {{{{{{new OpenApiseCurityScheme {reference = New Openapireference {type = type = referenceType.SecurityScheme，ID =“ Oauth2”}}，new [}}，new [] writeaccess“}}}）;}））

如果您的方案仅适用于某些操作，则可以通过操作过滤器应用它们。例如，以下过滤器添加了基于AuthorizeAttribute的存在的OAuth2要求：

 // SecurityRequiretementSoperationFilter.cspublic类SecurityRequirementsOperationFilter：ioperationFilter {public void Apply（OpenApioperation操作，FiperfilterContext Context）{//策略名称映射到scopesvar essirdscopes = scopesvar essirceScopes = contect.contoct.methodinfo.getCustomatTribute selectizeTribute（tepentriz.oftribute）。 > attr.policy）.distinct（）; if（requiresscopes.any（））{protip.responses.add（“ 401”，新的openapiresponse {description =“未授权”'}）; protive.Responses.add（“ 403”，，“，”，“ 403”，“，”新的OpenApiResponse {description =“ forbidden”}）; var oauthscheme = new OpenApiseCurityScheme {referenape = new Openapireference {type = referenceType.securityscheme，id =“ oauth2”}; oauth2}}; oauthscheme] = requiresscopes.tolist（）}}}}}}}}}}}}}

注意：如果您使用的是SwaggerUI中间件，则可以启用由发射安全元数据供电的Interactive OAuth2.0流。有关更多详细信息，请参见启用OAuth2.0流。

添加载体Auth的安全定义和要求

Services.AddSwaggergen（C => {C.AddseCurityDefinition（“ Bearerauth”，新的OpenApiseCuritySchemeScheme {type = SecuritySchemetype.http，scheme =“ Bearer”，BearerFormat =“ JWT”，使用BEARER SCOPEN ）; c.AddSecurityRequirement（新的OpenApiseCurityRequirlement {{{new OpenApiseCurityScheme {recement = new Openapireference {type = type = referenceType.securityscheme，id =“ bearerauth”}

继承和多态性

Swagger / OpenAPI定义了用于描述模式定义中的继承和多态性关系的allOf和oneOf关键词。例如，如果您使用的是共享共同属性的模型的基类，则可以使用allOf关键字来描述继承层次结构。或者，如果您的序列化器支持多态性序列化/避难所化，则可以使用oneOf关键字来记录所有“可能的”模式，以适用于按子类型变化的请求/响应。

启用继承

默认情况下，Swashbuckle平坦了继承层次结构。也就是说，对于派生的模型，将继承的属性与声明的属性一起列出。这可能会在产生的招摇中引起很多重复，尤其是在有多种亚型时。如果您使用客户端生成器（例如NSWAG），并且想维护生成的客户端模型中的继承层次结构，这也是有问题的。为了解决此问题，您可以应用UseAllOfForInheritance设置，这将利用allOf关键字通过生成的Swagger中的参考来合并继承的属性：

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可以选择其在哪些层次结构中所做的，并且不会在生成的Swagger中暴露出来。默认情况下，它将拾取与给定基本类型相同的组件定义的任何子类型。如果您想覆盖此行为，则可以提供自定义选择器函数：

 services.AddSwaggergen（c => {... c.useallofforinheritance（）; c.SelectSubTypesused（baseType => {return typef（startup）.assembly.getTypes（）。 }）}）;

注意：如果您使用的是swashbuckle注释库，它将包含一个基于基类定义上的SwaggerSubType属性的自定义选择器。这样，您可以使用简单的属性明确列出要公开的继承和/或多态性关系。要启用此行为，请查看注释文档。

描述歧视者

与oneOf和 /或allOf关键字一起，Swagger / OpenAPI支持基本模式定义上的discriminator字段。该关键字指向识别给定有效载荷所表示的特定类型的属性。除了属性名称外，歧视器描述还可以包括mapping ，该映射将鉴别值映射到特定的模式定义。

例如，Newtonsoft Serializer通过在JSON实例上排放/接受“ $ type”属性来支持多态性序列化/避难所。该属性的值将是给定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.SelectDiscriminatOrnAteNameusise（（（baseType）=>“ typeName”）; c.SelectDiscriminatorValueusing（（subtype）=> subtype.name.name）;}）;}）;}）;}）;

注意：如果您使用的是SwashBuckle注释库，则它包含基于基类定义上的SwaggerDiscriminator和SwaggerSubType属性的自定义选择器函数。这样，您可以使用简单的属性明确提供歧视元数据。要启用此行为，请查看注释文档。

swashbuckle.aspnetcore.swaggerui

将相对路径更改为UI

默认情况下，Swagger UI将暴露在“/Swagger”上。如有必要，您可以在启用Swaggerui中间件时进行更改：

 app.useswaggerui（c => {c.RoutepRefix =“ api-docs”}

更改文档标题

默认情况下，Swagger UI将具有通用文档标题。当您打开多个宣传页面时，可能很难区分它们。在启用Swaggerui中间件时，您可以更改它：

 app.useswaggerui（c => {c.documentTitle =“我的Swagger UI”;}

更改CSS或JS路径

默认情况下，Swagger UI包含默认的CSS和JS，但是如果您想更改路径或URL（例如使用CDN）：

 app.useswaggerui（c => {c.stylespath =“ https://cdnjs.cloudflare.com/ajax/ajax/libs/libs/swagger-ui/5.17.10/swagger-ui.min.min.css”; c.scriptbundle =“ htttps =” htttps ：//cdnjs.cloudflare.com/ajax/libs/swagger-ui/5.17.10/swagger-ui-bundle.min.js'; c.sscriptpresetsetspath =“ https：//cdnjs.cloudflare.com/ajax/ajax/libs /swagger-ui/5.17.10/swagger-ui-standalone-preset.min.js;}

列出多个宣传文件

在启用中间件时，您需要指定一个或多个Swagger端点（完全合格或相对于UI页面）来为UI供电。如果提供多个​​端点，则将它们列在页面的右上角，从而使用户可以在不同文档之间切换。例如，以下配置可用于记录API的不同版本。

 app.useswaggerui（c => {c.swaggerendpoint（“/swagger/v1/swagger.json”，“ v1 docs”）; c.swaggerendpoint（“/swagger/v2/v2/swagger.json”，“ v2 docs”）; }

应用Swagger-UI参数

Swagger-UI带有其自己的配置参数集，所有这些都在此处描述。在Swashbuckle中，其中大多数通过Swaggerui中间件选项浮出水面：

 app.useswaggerui（c => {c.defaultmodelexpandDepth（2）; c.defaultModelRendering（modeRrendering.model）; c.defaultModelSexpandDepth（-1）; c.displayoperationId（）; c.displayReqlayPlayOperation（）无）; [Mycustomplugin]; C.EnableValidator（）; C.Subtmethod.get，submitMethod.head）; ）=> {返回响应;}）;}）;

笔记

添加自定义插件时，请确保添加任何定义插件函数的自定义js文件。

注入自定义JavaScript

要调整行为，您可以通过将其添加到wwwroot文件夹中并指定中间件选项中的相对路径来注入其他JavaScript文件：

 app.useswaggerui（c => {c.injectjavascript（“/swagger-ui/custom.js”）;}

注意： InjectOnCompleteJavaScript和InjectOnFailureJavaScript选项已被删除，因为最新版本的Swagger-UI不会露出必要的挂钩。相反，它根据React和Redux的概念和模式提供了灵活的自定义系统。为了利用这一点，您需要提供index.html的自定义版本，如下所述。

自定义索引示例应用程序使用Swagger-UI插件系统提供了这种方法，提供了自定义的TOPBAR，并隐藏了信息组件。

注入自定义CSS

为了调整外观，您可以通过将其添加到wwwroot文件夹中并指定中间件选项中的相对路径来注入其他CSS样式表：

 app.useswaggerui（c => {c.InjectStyStyleSheet（“/Swagger-ui/custom.css”）;};}

自定义index.html

要自定义UI之外上面列出的基本选项，您可以提供自己的Swagger-UI index.html页面的版本：

 app.useswaggerui（c => {c.IndexStream =（）=> getType（）。汇编.getManifestResourceStream（“ custicuiiindex.swagger.swagger.index.html”）; //要求将文件添加为embedded resource}）;

要开始，您应该将自定义index.html基于默认版本

启用oauth2.0流

Swagger-UI拥有内置的支持，以参与OAuth2.0授权流。如Swagger JSON所指定的，它与授权和/或令牌端点进行交互，以获取后续API调用的访问令牌。请参阅添加安全定义和要求，以添加OAuth2.0元数据到生成的Swagger中。

如果您的Swagger端点包含适当的安全元数据，则应自动启用UI交互。但是，您可以在下面的以下设置中进一步自定义UI中的OAuth支持。有关更多信息，请参见Swagger-UI文档：

 app.useswaggerui（c => {c.oauthclientid（“ test-id”）; c.oauthcleentecret（“ test-secret”）; c.oauthusername（“ test-user”）; c.oauthrealm（“ test-realm”） ）c.oauthappname（“ test-app”）;字符串，字符串> {{“ foo”，“ bar”}}）;

使用客户端请求和响应拦截器

要根据Swagger-UI的请求和响应使用自定义拦截器，您可以将它们定义为配置中的JavaScript函数：

 app.useswaggerui（c => {c.usereQuestInterceptor（“（req）=> {req.headers ['x-my-custom-header'] ='mycustomvalue'; return req;}; c.useresponseSponseinterceptor（c.useresponseinterceptor（ （res）=> {console.log（'自定义拦截器拦截响应：'，res.url）;

在一系列方案中，您可能想将本地XSRF代币附加到所有请求：例如：

 app.useswaggerui（c => {c.UsereQuestInterceptor（“（req）=> {req.headers ['x-xsrf-token'] = localstorage.getItem（'xsrf-token'; return req;} }）;

swashbuckle.aspnetcore.annotations

安装和启用注释

1. 将以下Nuget软件包安装到您的ASP.NET核心应用程序中。

   Package Manager : Install-Package Swashbuckle.AspNetCore.Annotations
   CLI : dotnet add package Swashbuckle.AspNetCore.Annotations

2. 在Startup.cs的ConfigureServices方法中，在Swagger Config Block中启用注释：

    services.addswaggergen（c => {... c.enableannotations（）;}）;

富集操作元数据

启用注释后，您可以通过使用SwaggerOperationAttribute装饰动作来丰富生成的操作元数据。

 [httppost] [swaggerOperation（summary =“创建新产品”，description =“要求管理员特权”，aperationId =“ createProduct”，tags = new [] {] {“ publice”，“ property”，“ product”，“ propperse”}）] public iCultionResult create（[[[[[[[[[[[[[[[]来自Body]产品产品）

丰富响应元数据

ASP.NET Core提供了ProducesResponseTypeAttribute ，用于列出可以通过操作返回的不同响应。如上所述，这些属性可以与XML评论相结合，以在生成的招摇中对每个响应进行对人类友好的描述。如果您希望使用单个属性进行所有操作，并避免使用XML注释，则可以使用SwaggerResponseAttribute s：

 [httppost] [SwaggerResponse（201，“创建产品”，typeof（product））] [SwaggerResponse（400，“产品数据无效”）]公共iacuctionResult create（[来自Body]产品产品）

丰富参数元数据

您可以用SwaggerParameterAttribute注释“路径”，“ Query”或“ Query”绑定参数或属性（即用[FromRoute] ，[FromQuery]或[FromQuery]或[FromHeader] Parameter进行注释。

 [httpget] public iCultionResult getProducts（[FromQuery，SwaggerParameter（“搜索关键字”，必需= true）]字符串关键字）

丰富请求boby元数据

您可以用SwaggerRequestBodyAttribute注释“正文”绑定参数或属性（即用[FromBody]装饰），以丰富由SwashBuckle生成的相应RequestBody数据：

 [httppost]公共iCutionResult createproduct（[[来自Body，SwaggerRequestBody（“产品有效负载”，必需= true）]产品产品）

富集模式元数据

您可以使用SwaggerSchemaAttribute注释类或属性，以丰富由Swashbuckle生成的相应的Schema数据：

 [swaggerschema（必需= new [] {“ descript”}]]公共类产品{[[swaggerschema（“ the the the the the the the the the the the the the the the the the the the the the the the the the the the tre）= true）] public int int id {get;放; } [Swaggerschema（“产品描述”）]公共字符串描述{get;放; } [swaggerschema（“创建的日期”，格式=“ date”）] public dateTime datecreated {get;放; }}}

注意：在Swagger / OpenAPI中，序列化对象和包含的属性表示为Schema实例，因此为什么可以将此注释应用于类和属性。同样值得注意的是，“必需”属性被指定为顶级模式上的属性名称数组，而不是每个单独属性上的标志。

将模式过滤器应用于特定类型

SwaggerGen软件包提供了几个扩展点，包括用于自定义所有生成的模式的模式过滤器（此处描述）。但是，在某些情况下，最好将过滤器应用于特定模式。例如，如果您想在API中包含特定类型的示例。这可以通过用SwaggerSchemaFilterAttribute进行装饰来完成：

 // product.cs [swaggerschemafilter（typeof（productschemafilter））]公共类产品{...} // productschemafilter.cspublic类产品chemafilter：ischemafilter {public void applion（public void apply（openapischema schema，openapischema schema schema schema schema，schemafiltercontext context） [“ id”] = new OpenApiInteger（1），[“ description”] = new OpenApistring（“一个很棒的产品”）};}}}}

添加标签元数据

默认情况下，Swagger Generator将使用控制器名称标记所有操作。然后，该标签用于驱动Swagger-UI中的操作分组。如果您想为每个组提供一个描述，则可以通过SwaggerTagAttribute为每个控制器名称添加元数据：

 [Swaggertag（“创建，读取，更新和删除产品”）]公共类产品Controller {...}

注意：这将把上面的描述专门添加到名为“产品”的标签中。因此，如果您使用控制器名称以外的其他内容进行标记操作，则应避免使用此属性 - 例如，如果您使用TagActionsBy自定义标记行为。

列表遗传和多态性的已知亚型

如果您想使用Swashbuckle的继承和/或多态性行为，则可以使用注释明确指示给定的基本类型的“已知”子类型。这将覆盖默认选择器函数，该函数选择与基本类型相同的组件中的所有子类型，因此，当您启用注释时需要明确启用：

 // startup.csservices.addswaggergen（c => {c.enableannotations（enableAnnotations forinheritance：true，enableannotations forpolymormorphism：true）;}; // shape.cs; shape.cs [swaggersubtype（swaggersubtype（typeof（type of ectangle）] ]公共抽象类形状{}

用鉴别元素元素富集多态性基础类别

如果您正在使用注释来明确指示多态基本类型的“已知”亚型，则可以将SwaggerDiscriminatorAttribute与SwaggerSubTypeAttribute结合起来，以提供有关“歧视者”属性的其他元数据，然后将其纳入生成的Schema Schema定义：

 // startup.csservices.addswaggergen（c => {c.enableannotations（enableannotationsforinheritance：true，enableannotationsforpolymorplism：true）; // shape.cs; shape.cs [swaggerdiscriminator（swaggerdiscriminator（“ shapetype”） =“ Rectangle”）] [swaggerSubType（typeof（circle），indicminatorValue =“ circle”）]公共抽象类形状{public shapetype {get;放; }}}

这表明相应的有效载荷将具有“形状”属性以区分子类型，如果有效载荷代表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.aspnetcore.cli

直接从初创企业组装中取出Swagger

使用Swashbuckle设置了应用程序（请参阅“入门”），您可以使用Swashbuckle CLI工具直接从应用程序的启动组件中检索Swagger / OpenAPI JSON，然后将其写入文件。如果您想将Swagger Generation纳入CI/CD进程，或者您想在运行时从静态文件中使用它，这可能很有用。

它被包装为可通过dotnet SDK安装和使用的.NET工具。

配x该工具需要在运行时加载您的启动DLL及其依赖项。因此，您应该使用与应用程序兼容的dotnet SDK版本。例如，如果您的应用程序目标net6.0 ，则应使用SDK的6.0.xxx版本来运行CLI工具。如果它针对net8.0 ，则应使用SDK的8.0.xxx版本，等等。

将工具与.NET SDK一起使用

1. 作为全局工具安装

   dotnet tool install -g Swashbuckle.AspNetCore.Cli

2. 验证该工具是否正确安装

   swagger tofile --help

3. 从您的应用程序的启动组件中生成Swagger/ OpenAPI文档

   swagger tofile --output [output] [startupassembly] [swaggerdoc]

   在哪里 ...

• [输出]是将摇动json输出到的相对路径

• [startupaySembly]是您应用程序启动组件的相对路径

• [SwaggerDoc]是您要检索的Swagger文档的名称，如启动类中的配置

将工具与.NET 6.0 SDK或更高版本一起使用

1. 在您的项目根中，创建一个工具清单文件：

   dotnet new tool-manifest

2. 作为本地工具安装

   dotnet tool install Swashbuckle.AspNetCore.Cli

3. 验证该工具是否正确安装

   dotnet swagger tofile --help

4. 从您的应用程序的启动组件中生成Swagger / OpenAPI文档

   dotnet swagger tofile --output [output] [startupassembly] [swaggerdoc]

   在哪里 ...

• [输出]是将摇动json输出到的相对路径

• [startupaySembly]是您应用程序启动组件的相对路径

• [SwaggerDoc]是您要检索的Swagger文档的名称，如启动类中的配置

使用具有自定义主机配置的CLI工具

该工具将在“默认” Web主机的上下文中执行。但是，在某些情况下，您可能需要携带自己的主机环境，例如，如果您配置了自定义DI容器（例如AutoFac）。在这种情况下，Swashbuckle CLI工具为您的应用程序揭示了基于约定的挂钩。

也就是说，如果您的应用程序包含一个符合以下命名约定的类，则该类将用于为CLI工具提供主机。

• public class SwaggerHostFactory ，包含一种称为CreateHost的公共静态方法，带有返回类型IHost

• public class SwaggerWebHostFactory ，包含一种称为return type CreateWebHost IWebHost公共静态方法

例如，以下类可用于利用与您的应用程序相同的主机配置：

公共类SwaggerHostFactory {public static Ihost createHost（）{return program.CreateHostBuilder（new String [0]）。build（）;}}

swashbuckle.aspnetcore.redoc

将相对路径更改为UI

默认情况下，REDOC UI将暴露在“/API-DOCS”上。如有必要，您可以在启用重型中间件时进行更改：

 app.useredoc（c => {c.RoutepRefix =“ docs” ...}

更改文档标题

默认情况下，REDOC UI将具有通用文档标题。您可以在启用重型中间件时更改此操作：

 app.useredoc（c => {c.documentTitle =“我的api docs”; ...}

应用重复参数

重做使用其自己的配置参数集的船，所有这些都在此处介绍https://github.com/rebilly/rebilly/redoc/blob/main/main/readme.md#redoc-options-object。在swashbuckle中，其中大多数通过重做中间件选项浮出水面：

 app.useredoc（c => {c.specurl（“/v1/swagger.json”）; c.enableuntrustedspec（）; c.scrollyoffset（10）; c.hidehostname（）; c.hideHideShiDeWhideTohname（）; c.hidedownownloadbutton（） （200,201）; sortPropsalPhabetly（）;}）;

在同一UseReDoc(...)中多次使用c.SpecUrl("/v1/swagger.json")不会添加多个URL。

注入自定义CSS

为了调整外观，您可以通过将其添加到wwwroot文件夹中并指定中间件选项中的相对路径来注入其他CSS样式表：

 app.useredoc（c => {... c.InjectStylesHeet（“/redoc/custom.css”）;};}

还可以使用AdditionalItems属性来修改主题，请参阅https://github.com/rebilly/rebilly/redoc/blob/main/main/readme.md#redoc-options-object，了解更多信息。

 app.useredoc（c => {... c.configobject.additionalitems = ...}

自定义index.html

要自定义UI之外上面列出的基本选项，您可以提供自己的RETOC index.html页面的版本：

 app.useredoc（c => {c.indexstream =（）=> getType（）。汇编.getManifestResourceStream（“ customIndex.redoc.index.html”）; //要求将文件添加为嵌入式资源}）;

要开始，您应该将自定义index.html基于默认版本