Swashbuckle.AspNetCore CLI工具配置与自定义指南-优快云博客

本文链接：https://blog.youkuaiyun.com/gitblog_00987/article/details/148505556

Swashbuckle.AspNetCore CLI工具配置与自定义指南

Swashbuckle.AspNetCore Swashbuckle.AspNetCore：这是一个用于ASP.NET Core的Swagger文档生成器，适合为RESTful API生成API文档。特点包括自动生成API文档、支持多种输出格式（如Markdown、HTML等）、与ASP.NET Core集成良好等。项目地址: https://gitcode.com/gh_mirrors/sw/Swashbuckle.AspNetCore

前言

在现代API开发中，Swagger/OpenAPI规范已成为描述RESTful API的事实标准。Swashbuckle.AspNetCore作为.NET平台最流行的Swagger实现工具，不仅提供了运行时生成Swagger文档的能力，还包含了一个强大的CLI工具，用于在构建流程中生成静态Swagger文档。本文将深入探讨Swashbuckle.AspNetCore.Cli工具的使用方法和自定义技巧。

CLI工具概述

Swashbuckle.AspNetCore.Cli是一个.NET全局工具，它允许开发者直接从应用程序的启动程序集中提取Swagger/OpenAPI JSON文档，并将其写入文件。这种能力在以下场景中特别有价值：

需要将Swagger生成集成到CI/CD流程中
希望在运行时从静态文件提供Swagger文档
需要生成文档用于离线分析或文档系统集成

安装CLI工具

全局安装方式

对于需要跨项目使用的场景，推荐全局安装：

dotnet tool install -g Swashbuckle.AspNetCore.Cli

本地安装方式

对于项目特定的使用场景，可以采用本地安装：

dotnet new tool-manifest

安装本地工具：

dotnet tool install Swashbuckle.AspNetCore.Cli

重要提示：工具运行时需要加载你的启动DLL及其依赖项，因此必须使用与应用程序目标框架兼容的.NET SDK版本。例如，如果应用目标是net8.0，则应使用8.0.x版本的SDK运行CLI工具。

基本使用

验证安装

安装完成后，可以通过以下命令验证工具是否可用：

swagger tofile --help

生成Swagger文档

基本命令格式如下：

swagger tofile --output [输出路径] [启动程序集路径] [Swagger文档名称]

参数说明：

[输出路径]：生成的Swagger JSON文档的相对路径
[启动程序集路径]：应用程序启动程序集的相对路径
[Swagger文档名称]：应用程序中配置的Swagger文档名称

示例：

swagger tofile --output swagger/v1/swagger.json ./bin/Debug/net8.0/MyApp.dll v1

高级自定义：使用自定义主机配置

默认情况下，CLI工具会在"默认"Web主机上下文中执行。但对于某些高级场景，如使用了Autofac等自定义DI容器，你可能需要提供自己的主机环境。

Swashbuckle.AspNetCore.Cli提供了基于约定的钩子机制，允许应用程序提供自定义主机。只需在应用程序中创建符合以下任一命名约定的类：

SwaggerHostFactory类，包含返回IHost的CreateHost静态方法
SwaggerWebHostFactory类，包含返回IWebHost的CreateWebHost静态方法

实现示例

以下示例展示了如何复用应用程序的主机构建逻辑：

public class SwaggerHostFactory
{
    public static IHost CreateHost()
    {
        // 复用应用程序的主机构建逻辑
        var args = new string[0]; // 可根据需要传递参数
        return Program.CreateHostBuilder(args).Build();
    }
}