手把手教你ASP.NET Core：Web API文檔利器Swagger

Swagger是什麼？

本質上就是使用 OpenAPI 3.0 規範寫一份文檔，該文檔描述了 API 的各類狀態，你能夠拿着這份文檔部署在 Swagger-UI 上給對接的同事查看，也能夠在 SoapUI 等工具中進行測試。

添加並配置 Swagger 中間件

須要先安裝「Swashbuckle.AspNetCore」包，將 Swagger 生成器添加到 Startup.ConfigureServices 方法中的服務集合中：

services.AddSwaggerGen();

在 Startup.Configure 方法中，啓用中間件爲生成的 JSON 文檔和 Swagger UI 提供服務：

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

XML 註釋

• 在「解決方案資源管理器」中右鍵單擊該項目，而後選擇「編輯<project_name>.csproj」 。

• 手動將PropertyGroup添加：

  true

更改services.AddSwaggerGen();代碼以下：

services.AddSwaggerGen((c =>
{
    var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
    var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
    c.IncludeXmlComments(xmlPath);
}));

演示效果

小結

如今咱們終於把API文檔也搞定了，不再用傻傻的經過Word手工寫API文檔給前端了，而也不怕咱們更新了API而文檔沒有同步更新。