Swagger是一個(gè)應(yīng)用很廣的API文檔框架跛溉。我們可以利用Swashbuckle.AspNetCore來(lái)實(shí)現(xiàn)NetCore Web API的自動(dòng)接口文檔焊切，并以一個(gè)web ui的方式查看swagger樣式的API接口文檔及調(diào)試。
通常我們用NetCore編寫Web API給前端開(kāi)發(fā)者芳室、手機(jī)App或其它服務(wù)調(diào)用专肪，通過(guò)這種自動(dòng)生成的API文檔能實(shí)時(shí)反應(yīng)接口的變化，避免自己編寫的API文檔和代碼沒(méi)有保持一致的問(wèn)題堪侯。
步驟很簡(jiǎn)單：
1. 添加Swashbuckle.AspNetCore庫(kù)嚎尤，通過(guò)Nuget搜索添加
<PackageReference Include="Swashbuckle.AspNetCore" Version="2.4.0" />
2. 注入Swagger API描述json的生成服務(wù)
public void ConfigureServices(IServiceCollection services)
{
services.AddMvc();
services.AddSwaggerGen(c =>
{
c.SwaggerDoc("v1", new Info { Title = "My API", Version = "v1" });
});
}
3. App添加使用Swagger和ui展示
public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
app.UseMvc();
app.UseSwagger();
app.UseSwaggerUI(c =>
{
c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
});
}
這里注意Endpoint值可以是相對(duì)值也可以是絕對(duì)值，如果是相對(duì)值伍宦，"/swagger/v1/swagger.json"是缺省值芽死，比如你的服務(wù)部署在http://www.xxx.com/test下，則這個(gè)值得改為"/test/swagger/v1/swagger.json"
這樣就可以了次洼，在瀏覽器里輸入地址加/swagger就可以看到swagger樣式的API文檔了关贵。
再進(jìn)一步，我們把中文注釋什么的也加到API文檔里滓玖，比如
/// <summary>
/// Get請(qǐng)求注釋
/// </summary>
/// <returns></returns>
// GET api/values
[HttpGet]
public IEnumerable<string> Get()
{
return new string[] { "value1", "value2" };
}
只需2個(gè)步驟：
1. 編譯的時(shí)候生成xml文檔文件
點(diǎn)擊項(xiàng)目 右鍵 屬性 在生成tab頁(yè)里輸出里勾選XML文檔文件
2. 在注入swagger服務(wù)時(shí)添加代碼
services.AddSwaggerGen(c =>
{
c.SwaggerDoc("v1", new Info { Title = "My API", Version = "v1" });
var basePath = Microsoft.Extensions.PlatformAbstractions.PlatformServices.Default.Application.ApplicationBasePath;
var xmlPath = System.IO.Path.Combine(basePath, "do.xml");
c.IncludeXmlComments(xmlPath);
});
注意參數(shù)里的xml文件名必須和第一步里設(shè)置的xml文件名一致坪哄。
其實(shí)就是讓swagger生成json時(shí)去讀取生成的xml文檔，然后組合在一起势篡。
最后我們?cè)倏纯葱Ч?/p>
