003 在.Net Core 中使用 Swagger
引出問題
有的時候我們編寫了一個API項目,但是沒有太多時間來編寫接口文檔,這個時候會增加與消費者(API)調用者的溝通成本,這個時候Swagger的使用就很有必要了.
在Asp .Net Core Web API 中使用Swagger
-
在WebApi,所在的項目中,通過Nuget安裝
SwashBuckle.AspNetCore
包,此包依賴如下包:- SwashBuckle.AspNetCore.Swagger
- SwashBuckle.AspNetCore.SwaggerGen
- SwashBuckle.AspNetCore.SwaggerUI
- SwashBuckle.AspNetCore.ApiDescription.Server
-
在
Startup.cs
類的ConfigureServices
方法中配置如下注入:
services.AddSwaggerGen(options =>
{
options.SwaggerDoc("v1", new OpenApiInfo { Title = "WebAPI項目的含義名稱", 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");
});
到此在項目中應用Swagger的過程基本完成,是不是很簡單,下面啓動服務看效果:
在接口中顯示文檔描述
有的時候我們需要再Swagger文檔中顯示接口描述,那麼我們應該怎麼做呢?
- 我們在項目中首相需要給接口,以及實體類加上C#文檔註釋(必須要現有文檔註釋).
- 生成操作如下:
- 我們在WebApi所在的項目中,在其屬性中的生成頁面中,勾選上XML文檔即可.
此處需要 注意 一點,如果我們也想讓輸入輸出參數的文檔註釋也顯示再Swagger
中那麼我們也需要將輸入輸出參數實體類所在的項目,也需要生成XML文檔文件
,並且我們需要將生成好的文檔文件放到Asp .Net Core運行所在的目錄中.
在Swagger文檔中過濾接口
有的時候有的接口我們並不想將整個項目下的所有API接口都顯示再Swagger文檔中,暴露給消費者,那麼我們應該怎麼做呢?
很簡單,我們只需要再不想暴露出來的Action上加上特性[ApiExplorerSettings(IgnoreApi = true)]
即可.
示例代碼:
[HttpGet]
[ApiExplorerSettings(IgnoreApi = true)]
public ActionResult Index(string appKey , string userName ,string userPwd)
{
//todo
}
參考文章地址: 在.NetCore WebApi中過濾Swagger文檔顯示接口方法