怎么在.Net Core WebAPI下给Swagger增加导出离线文档功能

在开发.Net Core WebAPI项目时，Swagger是一个非常流行的工具，用于生成和展示API文档。它不仅提供了交互式的API文档界面，还允许开发者直接在浏览器中测试API。然而，在某些情况下，我们可能需要将Swagger生成的API文档导出为离线文档，以便在没有网络连接的情况下查看或分享给团队成员。本文将介绍如何在.Net Core WebAPI项目中为Swagger增加导出离线文档的功能。

1. 安装必要的NuGet包

首先，我们需要安装一些必要的NuGet包来支持Swagger和导出功能。在项目中，确保已经安装了以下包：

• Swashbuckle.AspNetCore：用于生成Swagger文档。
• Swashbuckle.AspNetCore.SwaggerUI：用于提供Swagger UI界面。
• Swashbuckle.AspNetCore.SwaggerGen：用于生成Swagger JSON文档。

如果还没有安装这些包，可以通过NuGet包管理器或命令行安装：

dotnet add package Swashbuckle.AspNetCore
dotnet add package Swashbuckle.AspNetCore.SwaggerUI
dotnet add package Swashbuckle.AspNetCore.SwaggerGen

2. 配置Swagger

在Startup.cs文件中，配置Swagger以生成API文档。以下是一个基本的配置示例：

public void ConfigureServices(IServiceCollection services)
{
    services.AddControllers();
    services.AddSwaggerGen(c =>
    {
        c.SwaggerDoc("v1", new OpenApiInfo { Title = "My API", Version = "v1" });
    });
}

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    if (env.IsDevelopment())
    {
        app.UseDeveloperExceptionPage();
    }

    app.UseSwagger();
    app.UseSwaggerUI(c =>
    {
        c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
    });

    app.UseRouting();
    app.UseEndpoints(endpoints =>
    {
        endpoints.MapControllers();
    });
}

3. 添加导出功能

为了导出Swagger文档，我们可以使用Swashbuckle.AspNetCore.Cli工具。这个工具可以将Swagger JSON文档导出为HTML、Markdown等格式。

首先，安装Swashbuckle.AspNetCore.Cli包：

dotnet tool install --global Swashbuckle.AspNetCore.Cli

安装完成后，我们可以使用以下命令将Swagger JSON文档导出为HTML文件：

swagger tofile --output swagger.json ./bin/Debug/netcoreapp3.1/MyApi.dll v1
swagger tohtml --output swagger.html swagger.json

上述命令将生成一个swagger.html文件，其中包含了Swagger文档的HTML版本。

4. 自动化导出过程

为了简化导出过程，我们可以将上述命令集成到项目的构建过程中。在.csproj文件中添加一个PostBuildEvent，以便在每次构建后自动导出Swagger文档：

<Target Name="PostBuild" AfterTargets="PostBuildEvent">
  <Exec Command="swagger tofile --output swagger.json $(TargetPath) v1" />
  <Exec Command="swagger tohtml --output swagger.html swagger.json" />
</Target>

这样，每次构建项目时，都会自动生成swagger.html文件。

5. 提供下载链接

为了方便用户下载导出的Swagger文档，我们可以在Swagger UI中添加一个下载链接。在Startup.cs文件中，修改UseSwaggerUI配置：

app.UseSwaggerUI(c =>
{
    c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
    c.InjectStylesheet("/swagger-ui/custom.css");
    c.InjectJavascript("/swagger-ui/custom.js");
});

然后，在wwwroot/swagger-ui目录下创建custom.js文件，并添加以下代码：

window.onload = function() {
    var downloadLink = document.createElement("a");
    downloadLink.href = "/swagger.html";
    downloadLink.innerText = "Download Offline Documentation";
    downloadLink.style.position = "absolute";
    downloadLink.style.top = "10px";
    downloadLink.style.right = "10px";
    document.body.appendChild(downloadLink);
};

这样，用户在访问Swagger UI时，会看到一个“Download Offline Documentation”的链接，点击即可下载导出的Swagger文档。

6. 总结

通过以上步骤，我们成功地在.Net Core WebAPI项目中为Swagger增加了导出离线文档的功能。这不仅方便了开发者在没有网络连接的情况下查看API文档，还使得文档的分享和存档变得更加容易。希望本文对你在.Net Core项目中使用Swagger有所帮助。