[ASP.NET Core]如何使用SwaggerAPI說明文件

發表於 | | 閱讀次數:

在開發API站台時，時常要與前端開發者做對接，Swagger提供了很完善的說明文件，也可以立即做測試
接下來介紹如何ASP.NET Core中使用Swagger產生說明文件

安裝套件

Swagger主要有三個套件

  1. Swashbuckle.AspNetCore.Swagger: 公開 SwaggerDocument 物件作為 JSON 端點。
  2. Swashbuckle.AspNetCore.SwaggerGen: 可以從Model、Controller、Router 等 建立 SwaggerDocument
  3. Swashbuckle.AspNetCore.SwaggerUI: 可解析 Swagger Json 來產生畫面

從 Visual Studio 中可以在套件管理員中找到這三個套件

設定Swagger MiddleWare

在ConfigureServices 加入 Swagger產生器

1
2
3
4
5
6
7
8
9
10
11
12
public void ConfigureServices(IServiceCollection services)
{
    services.AddControllers();
    /// 加入Swagger產生器到服務集合
    services.AddSwaggerGen(c =>
    {
        c.SwaggerDoc("v1", new OpenApiInfo
        {
            Title = "My API", Version = "V1"
        });
    });
}

在Startup.Configure方法中，啟用Swagger Middleware 用來產生json文件與Swagger UI

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    if (env.IsDevelopment())
    {
        app.UseDeveloperExceptionPage();

    /// 使用 Swagger 產生json端點文件
    app.UseSwagger()
    /// 啟用SwaggerUI 並根據Swagger.json產生畫面
    app.UseSwaggerUI(c => { c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1"); })
    app.UseHttpsRedirection()
    app.UseRouting()
    app.UseAuthorization()
    app.UseEndpoints(endpoints =>
    {
        endpoints.MapControllers();
    });
}

接著編譯一下並啟動 瀏覽https://localhost:<port>/swagger 就可以看到Swagger的API說明文件了

剛剛設定的Json端點文件會產生在 https://localhost:<port>/swagger/v1/swagger.json

自訂Swagger API 說明資訊

你也可以自行設定額外的Swagger API的說明資訊 在 ConfigureServices 設定

1
2
3
4
5
6
7
8
9
10
services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new OpenApiInfo
    {
        Title = "My API", 
        Version = "V1",
        Contact = new OpenApiContact { Name = "Bryan", Email = "d58526@gmail.com"},
        Description ="我的第一個測試API",
    });
});

在Swagger上加入Controller中或Model的註解

在程式當中所寫的註解，都可以透過Swagger產生說明文件，讓使用API的人更加了解API的意義及所需參數

我自訂了一個簡單的Controller

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
/// <summary>
/// 使用者服務
/// </summary>
[ApiController]
[Route("api/[controller]")]
public class UserController : ControllerBase
{
    private List<UserInfo> _userInfos = new List<UserInfo>
    {
        new UserInfo {Id = 1, Account = "Test1", Name = "Test1Name", Phone = "123456"},
        new UserInfo {Id = 2, Account = "Test2", Name = "Test2Name", Phone = "789123"},
        new UserInfo {Id = 3, Account = "Test3", Name = "Test3Name", Phone = "012345"},
    };
    
    /// <summary>
    /// 取得使用者清單
    /// </summary>
    /// <returns></returns>
    [HttpGet]
    public IEnumerable<UserInfo> Get()
    {
        return this._userInfos;
    }
    /// <summary>
    /// 取得單一使用者
    /// </summary>
    /// <param name="id">編號</param>
    /// <returns></returns>
    [HttpGet("{id}")]
    public UserInfo Get(int id)
    {
        return this._userInfos.FirstOrDefault(item => item.Id == id);
    }
    /// <summary>
    /// 新增使用者
    /// </summary>
    /// <param name="userInfo">使用者資訊</param>
    [HttpPost]
    public void Post([FromBody]UserInfo userInfo)
    {
        this._userInfos.Add(userInfo);
    }
    /// <summary>
    /// 更新使用者名稱
    /// </summary>
    /// <param name="id">編號</param>
    /// <param name="name">名稱</param>
    [HttpPut("{id}")]
    public void Put(int id, [FromBody]string name)
    {
        var user = this._userInfos.FirstOrDefault(item => item.Id == id);
        user.Name = name;
    }
    /// <summary>
    /// 刪除使用者
    /// </summary>
    /// <param name="id">編號</param>
    [HttpDelete("{id}")]
    public void Delete(int id)
    {
        this._userInfos.RemoveAll(item => item.Id == id);
    }
}

自訂了一個簡單的類別 UserInfo

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
/// <summary>
/// 使用者資訊
/// </summary>
public class UserInfo
{
    /// <summary>
    /// 編號
    /// </summary>
    public int Id { get; set; }
    /// <summary>
    /// 帳號
    /// </summary>
    public string Account { get; set; }
    /// <summary>
    /// 名稱
    /// </summary>
    public string Name { get; set; }
    /// <summary>
    /// 電話號碼
    /// </summary>
    public string Phone { get; set; }
}

接下來要讓專案產生註解的XML 並加入到Swagger中

打開專案檔 加入

1
2
3
<PropertyGroup>
  <GenerateDocumentationFile>true</GenerateDocumentationFile>
</PropertyGroup>

就會在編譯的時候 在組態的同名資料夾下會有檔名與專案同名的XML文件
這個XML文件的內容就是程式碼的註解

接下來要將這個註解XML檔案加入到Swagger中 在ConfigureServices加入設定

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new OpenApiInfo
    {
        Title = "My API",
        Version = "V1",
        Contact = new OpenApiContact {Name = "Bryan", Email = "d58526@gmail.com"},
        Description = "我的第一個測試API",
    });
    
    /// 加入xml檔案到swagger
    var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
    var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
    c.IncludeXmlComments(xmlPath);
});

重新執行就會看到剛剛所寫的程式碼註解，也有完整的類別說明，提高API文件的可讀性

範例程式

結論

透過Swagger產生API說明文件的方式，可以節省開發人員撰寫額外的文檔時間，又可以解決文件與程式碼的同步問題，同時產生的文檔也可以立即進行測試，對於前後端開發者的對接可以增加開發效率。