查看或下载示例代码（如何下载）
Swashbuckle 有三个主要组成部分：
- Swashbuckle.AspNetCore.Swagger：将 对象公开为 JSON 终结点的 Swagger 对象模型和中间件。
- Swashbuckle.AspNetCore.SwaggerGen：从路由、控制器和模型直接生成 对象的 Swagger 生成器。 它通常与 Swagger 终结点中间件结合使用，以自动显示 Swagger JSON。
- Swashbuckle.AspNetCore.SwaggerUI：Swagger UI 工具的嵌入式版本。 它解释了 Swagger JSON，以便为描述 Web API 功能构建丰富、可自定义的体验。 它包括针对公共方法的内置测试工具。
可以使用以下方法来添加 Swashbuckle：
将 Swagger 生成器添加到 方法中的服务集合中：
在 方法中，启用中间件为生成的 JSON 文档和 Swagger UI 提供服务：
在开发过程中，前述的 方法调用会启用 Swagger UI 工具的嵌入版本。 这取决于静态文件中间件。 如果以 .NET Framework 或 .NET Core 1.x 为目标，请将 Microsoft.AspNetCore.StaticFiles NuGet 包添加到项目。
启动应用，并导航到 。 生成的描述终结点的文档显示在 OpenAPI 规范 (openapi.json) 中。
可在 找到 Swagger UI。 通过 Swagger UI 浏览 API，并将其合并其他计划中。
如果使用目录及 IIS 或反向代理，请使用 前缀将 Swagger 终结点设置为相对路径。 例如，。 使用 指示应用在 URL 的真实根目录中查找 JSON 文件（如果使用，加上路由前缀）。 例如，请使用 而不是 。
Swagger 提供了为对象模型进行归档和自定义 UI 以匹配你的主题的选项。
在 类中，添加以下命名空间：
传递给 方法的配置操作会添加诸如作者、许可证和说明的信息：
在 类中，导入以下命名空间来使用 类：
使用 类修改 UI 中显示的信息：
Swagger UI 显示版本的信息：
可使用以下方法启用 XML 注释：
启用 XML 注释，为未记录的公共类型和成员提供调试信息。 警告消息指示未记录的类型和成员。 例如，以下消息指示违反警告代码 1591：
要在项目范围内取消警告，请定义要在项目文件中忽略的以分号分隔的警告代码列表。 将警告代码追加到 也会应用 C# 默认值。
要仅针对特定成员取消警告，请将代码附入 #pragma warning 预处理程序指令中。 此方法对于不应通过 API 文档公开的代码非常有用。在以下示例中，将忽略整个 类的警告代码 CS1591。 在类定义结束时还原警告代码的强制执行。 使用逗号分隔的列表指定多个警告代码。
将 Swagger 配置为使用按照上述说明生成的 XML 文件。 对于 Linux 或非 Windows 操作系统，文件名和路径区分大小写。 例如， 文件在 Windows 上有效，但在 Ubuntu 上无效。
在上述代码中，反射用于生成与 Web API 项目相匹配的 XML 文件名。 AppContext.BaseDirectory属性用于构造 XML 文件的路径。 一些 Swagger 功能（例如，输入参数的架构，或各自属性中的 HTTP 方法和响应代码）无需使用 XML 文档文件即可起作用。 对于大多数功能（即方法摘要以及参数说明和响应代码说明），必须使用 XML 文件。
通过向节标题添加说明，将三斜杠注释添加到操作增强了 Swagger UI。 执行 操作前添加 <summary> 元素：
Swagger UI 显示上述代码的 元素的内部文本：
生成的 JSON 架构驱动 UI：
将 <remarks> 元素添加到 操作方法文档。 它可以补充 元素中指定的信息，并提供更可靠的 Swagger UI。 元素内容可包含文本、JSON 或 XML。
请注意带这些附加注释的 UI 增强功能：
使用 命名空间中找到的属性来标记模型，以帮助驱动 Swagger UI 组件。
将 属性添加到 类的 属性：
此属性的状态更改 UI 行为并更改基础 JSON 架构：
将 属性添加到 API 控制器。 这样做的目的是声明控制器的操作支持 application/json 的响应内容类型：
“响应内容类型”下拉列表选此内容类型作为控制器的默认 GET 操作：
随着 Web API 中的数据注释的使用越来越多，UI 和 API 帮助页变得更具说明性和更为有用。
使用 Web API 的开发人员最关心的问题是返回的内容，特别是响应类型和错误代码（如果不标准）。 在 XML 注释和数据注释中表示响应类型和错误代码。
操作成功后返回 HTTP 201 状态代码。 发布的请求正文为 NULL 时，将返回 HTTP 400 状态代码。 如果 Swagger UI 中没有提供合适的文档，那么使用者会缺少对这些预期结果的了解。 在以下示例中，通过添加突出显示的行解决此问题：
Swagger UI 现在清楚地记录预期的 HTTP 响应代码：
在 ASP.NET Core 2.2 或更高版本中，约定可以用作使用 显式修饰各操作的替代方法。 有关详细信息，请参阅使用 Web API 约定。
为了支持 修饰，Swashbuckle.AspNetCore.Annotations 包提供了用于启用和丰富响应、架构和参数元数据的扩展。
默认 UI 既实用又可呈现。 但是，API 文档页应代表品牌或主题。 将 Swashbuckle 组件标记为需要添加资源以提供静态文件，并构建文件夹结构以托管这些文件。
如果以 .NET Framework 或 .NET Core 1.x 为目标，请将 Microsoft.AspNetCore.StaticFiles NuGet 包添加到项目：
如果以 .NET Core 2.x 为目标并使用元包，则已安装上述 NuGet 包。
启用静态文件中间件：
若要插入其他 CSS 样式表，请将其添加到项目的 wwwroot 文件夹中，并在中间件选项中指定相对路径：
- 使用 Swagger 文档改进开发人员的 API 体验
版权声明：
本文来自互联网用户投稿，该文观点仅代表作者本人，不代表本站立场。本站仅提供信息存储空间服务，不拥有所有权，不承担相关法律责任。
如若内容造成侵权、违法违规、事实不符，请将相关资料发送至xkadmin@xkablog.com进行投诉反馈，一经查实，立即处理！
转载请注明出处，原文链接：https://www.xkablog.com/rfx/18927.html