怎么在.Net Core WebAPI下給Swagger增加導出離線文檔功能

怎么在.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有所幫助。