Swagger這個優秀的開源專案相信大家都用過，不多介紹了，這裡簡單記錄一下使用過程。

開源地址：https://github.com/domaindrivendev/Swashbuckle.AspNetCore

在專案中新增元件

Install-Package Swashbuckle.AspNetCore

下面用最少的程式碼完成接入，在Startup啟動項中配置。

public void ConfigureServices(IServiceCollection services)
{
    ...
    services.AddSwaggerGen(x =>
    {
        x.SwaggerDoc("v1", new Microsoft.OpenApi.Models.OpenApiInfo
        {
            Version = "v1.0.0",
            Title = "Api",
            Description = "XXX Api"
        });
    });
    ...
}
 

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    ...

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

這樣便完成了，swagger會自動發現我們在controller中寫的api，預設開啟頁面為：~/swagger。

同時還可以讓其支援分組展示，只需要像上面一樣配置多個節點資訊介面，如下面程式碼：

services.AddSwaggerGen(options =>
{
    options.SwaggerDoc("v1", new Microsoft.OpenApi.Models.OpenApiInfo
    {
        Version = "v1.0.0",
        Title = "Api1",
        Description = "XXX Api1"
    });

    options.SwaggerDoc("v2", new Microsoft.OpenApi.Models.OpenApiInfo
    {
        Version = "v1.0.0",
        Title = "Api2",
        Description = "XXX Api2"
    });
});
 

app.UseSwaggerUI(c =>
{
    c.SwaggerEndpoint("/swagger/v1/swagger.json", "API1");
    c.SwaggerEndpoint("/swagger/v2/swagger.json", "API2");
});

如果在控制器中不指定介面的分組名稱，那麼每個分組都會顯示這個介面，如果需要單獨指定可以使用特性[ApiExplorerSettings(GroupName = "v1")]這樣。

如果想要顯示介面的註釋，模型的註釋等資訊，需要我們將對應的專案設定輸出XML檔案，並在程式碼中使用options.IncludeXmlComments(xxx.xml)即可。

下面來說一下swagger的一些其它功能，當我們介面開啟了JWT方式的認證，預設swagger是不支援的，需要我們手動去適配一下。

需要額外新增一個元件

Install-Package Swashbuckle.AspNetCore.Filters

context.Services.AddSwaggerGen(options =>
{
    ...

    var security = new OpenApiSecurityScheme
    {
        Description = "<b>please enter <code>Bearer {Token}</code> for authentication.</b>",
        Name = "Authorization",
        In = ParameterLocation.Header,
        Type = SecuritySchemeType.ApiKey
    };

    options.AddSecurityDefinition("oauth2", security);
    options.AddSecurityRequirement(new OpenApiSecurityRequirement { { security, null } });
    options.OperationFilter<AddResponseHeadersFilter>();
    options.OperationFilter<AppendAuthorizeToSummaryOperationFilter>();
    options.OperationFilter<SecurityRequirementsOperationFilter>();
});

現在UI介面便會出現小綠鎖，這樣就可以很方便的在swagger上進行需要授權的介面除錯工作了。

同時swagger還支援一些高階操作，比如自定義UI介面、注入JS、CSS程式碼，因為這個用的不是很多，實際要用的時候可以去GitHub檢視使用方法。

// Customize index.html
app.UseSwaggerUI(c =>
{
    c.IndexStream = () => GetType().Assembly.GetManifestResourceStream("CustomUIIndex.Swagger.index.html");
});

// Inject Custom CSS
app.UseSwaggerUI(c =>
{
    ...
    c.InjectStylesheet("/swagger-ui/custom.css");
}

這裡還要說一下swagger的過濾器，我們可以實現IDocumentFilter介面，來實現自定義的介面排序，個性化介面描述，以及各種騷操作，比如我們想要隱藏某些API，當然隱藏API可以使用.NET Core 的特性[ApiExplorerSettings(IgnoreApi = true)]實現。

這裡隱藏是指不在swaggerUI中顯示，實際介面還是存在的。

public class SwaggerDocumentFilter : IDocumentFilter
{
    public void Apply(OpenApiDocument swaggerDoc, DocumentFilterContext context)
    {
        var tags = new List<OpenApiTag>
        {
            new OpenApiTag {
                Name = "Authentication",
                Description = "Authentication",
                ExternalDocs = new OpenApiExternalDocs { Description = "Authentication" }
            },
            new OpenApiTag {
                Name = "Localization",
                Description = "Localization",
                ExternalDocs = new OpenApiExternalDocs { Description = "Localization" }
            }
        };

        swaggerDoc.Tags = tags.OrderBy(x => x.Name).ToList();

        var apis = context.ApiDescriptions.Where(x => x.RelativePath.Contains("abp"));
        if (apis.Any())
        {
            foreach (var item in apis)
            {
                swaggerDoc.Paths.Remove("/" + item.RelativePath);
            }
        }
    }
}

上面這段程式碼，使用了abp框架搭建的專案，abp預設實現了一部分介面，如果我們不需要的話就可以使用上面的方式進行過濾。

最後一點，如果我們用了第三方框架，像上面說的abp，或者使用了動態API生成的元件，比如：Plus.AutoApi，想要在swagger中顯示出api介面，需要新增下面這句程式碼。

context.Services.AddSwaggerGen(options =>
{
    ...
    options.DocInclusionPredicate((docName, description) => true);
    ...
});

swagger推出的同時還推出了一款工具ReDoc，下面也簡單介紹一下。

ReDoc和swagger比較類似，只是一個文件展示工具，不提供介面除錯的功能。

他們的使用方式基本一致，先在專案中新增一下元件

Install-Package Swashbuckle.AspNetCore.ReDoc

在OnApplicationInitialization中直接新增一句配置即可。

app.UseReDoc();

它支援多種引數選項，可以自行檢視，預設開啟頁面為：~/api-docs，下面是他的UI介面。