引出問題

有的時候我們編寫了一個API項(xiàng)目,但是沒有太多時間來編寫接口文檔,這個時候會增加與消費(fèi)者(API)調(diào)用者的溝通成本,這個時候Swagger的使用就很有必要了.

在Asp .Net Core Web API 中使用Swagger

1. 在WebApi,所在的項(xiàng)目中,通過Nuget安裝SwashBuckle.AspNetCore包,此包依賴如下包:

• SwashBuckle.AspNetCore.Swagger

• SwashBuckle.AspNetCore.SwaggerGen

• SwashBuckle.AspNetCore.SwaggerUI

• SwashBuckle.AspNetCore.ApiDescription.Server

2. 在Startup.cs類的ConfigureServices方法中配置如下注入:

services.AddSwaggerGen(options =>
{
    options.SwaggerDoc("v1", new OpenApiInfo { Title = "WebAPI項(xiàng)目的含義名稱", Version = "v1" });
    //添加中文注釋
    var basePath = Path.GetDirectoryName(typeof(Program).Assembly.Location);
    var commentsFileName = typeof(Program).Assembly.GetName().Name   ".XML";
    var xmlPath = Path.Combine(basePath, commentsFileName);

    options.IncludeXmlComments(xmlPath);

    //添加Model類的注釋
    var modelFileName = "Leisure.BabakuaiBus.DtoModels.xml";
    var modelXmlPath = Path.Combine(basePath, modelFileName);
    options.IncludeXmlComments(modelXmlPath);

    options.DocInclusionPredicate((docName, description) => true);
});

3.在Startup.cs類的Configure方法中,啟用如下中間件:

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

到此在項(xiàng)目中應(yīng)用Swagger的過程基本完成,是不是很簡單,下面啟動服務(wù)看效果:

在接口中顯示文檔描述

有的時候我們需要再Swagger文檔中顯示接口描述,那么我們應(yīng)該怎么做呢?

1. 我們在項(xiàng)目中首相需要給接口,以及實(shí)體類加上C#文檔注釋(必須要現(xiàn)有文檔注釋).

2. 生成操作如下:

• 我們在WebApi所在的項(xiàng)目中,在其屬性中的生成頁面中,勾選上XML文檔即可.

此處需要 注意 一點(diǎn),如果我們也想讓輸入輸出參數(shù)的文檔注釋也顯示再Swagger中那么我們也需要將輸入輸出參數(shù)實(shí)體類所在的項(xiàng)目,也需要生成XML文檔文件,并且我們需要將生成好的文檔文件放到Asp .Net Core運(yùn)行所在的目錄中.

在Swagger文檔中過濾接口

有的時候有的接口我們并不想將整個項(xiàng)目下的所有API接口都顯示再Swagger文檔中,暴露給消費(fèi)者,那么我們應(yīng)該怎么做呢?
很簡單,我們只需要再不想暴露出來的Action上加上特性[ApiExplorerSettings(IgnoreApi = true)]即可.

示例代碼:

[HttpGet]
[ApiExplorerSettings(IgnoreApi = true)]
public ActionResult Index(string appKey , string userName ,string userPwd)
{
	//todo
}

參考文章地址: 在.NetCore WebApi中過濾Swagger文檔顯示接口方法

使用Swagger的其它注意事項(xiàng):