iT邦幫忙

第 12 屆 iThome 鐵人賽

DAY 9
3
Modern Web

我與 ASP.NET Core 的 30天系列 第 9

[Day09]使用Swagger自動建立清晰明瞭的REST API文件 - 我與 ASP.NET Core 的 30天

在寫Web API 的時候,通常也需要提供清晰明瞭的文件供對接者查看,不過撰寫文件需要花非常多時間,也必須制定出文件規範才能讓對接的使用者容易明瞭,~~而且工程師不喜歡寫文件,~~這時候可以透過Swagger / OpenAPI 來為我們產出良好的文件吧

Swagger/OpenAPI 是什麼?

Swagger 是一間名為SmartBear Software 的公司,開發出的REST API 的工具,可以幫助設計、構建、記錄和使用REST API,後來貢獻給OpenAPI Initiative,並公開讓所有人都能夠使用。 這兩個名稱可交替使用;不過,OpenAPI 是慣用名稱。

為什麼要用Swagger/OpenAPI

在一般的工作情境中,開發人員要寫API文件時,很容易就會去使用Word、Excel,抑或會使用HackMD作為文件的提供,但是這類的文件,會有維護與修改的問題,比如改了參數但是忘記更新文件,或是手誤打錯,都會是溝通成本,而Swagger能夠自動生成API文件,並能在線上進行測試,正好可以解決上述問題。

NSwag

這邊主要選用NSwag的主要原因:

  • 提供 Swagger UI 和 Swagger 產生器。
  • 提供彈性的程式碼產生功能
    NSwag提供著強大且豐富的功能,可以讓我們在使用上有更良好的體驗。

安裝NSwag

首先我們在昨天的專案底下的安裝Nuget套件
dotnet add package NSwag.AspNetCore

安裝完畢之後先到Startup.ConfigureServices方法中,註冊Swagger服務

public void ConfigureServices(IServiceCollection services)
{
    services.AddScoped<BlogContext>();
    services.AddControllers()
            .AddJsonOptions(options =>
                {
                    options.JsonSerializerOptions.IgnoreNullValues = true;
                });

    
    services.AddOpenApiDocument(); // 註冊服務加入 OpenAPI 文件
}

接著設定Middleware

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    if (env.IsDevelopment())
    {
        app.UseDeveloperExceptionPage();
    }
    app.UseOpenApi();    // 啟動 OpenAPI 文件
    app.UseSwaggerUi3(); // 啟動 Swagger UI

    app.UseHttpsRedirection();
    app.UseRouting();
    app.UseAuthorization();

    app.UseEndpoints(endpoints =>
    {
        endpoints.MapControllers();
    });
}

設定完畢之後在cmd底下輸入dotnet run啟動專案後,在網址列輸入 https://localhost:5001/swagger 即可看到Swagger UI的畫面
https://ithelp.ithome.com.tw/upload/images/20200923/20129389sQrktZpZIR.png

可以看到Swagger幫我們把每一個API端點的文件都產出,

接著我們可以點開一個端點看到以下內容
https://ithelp.ithome.com.tw/upload/images/20200923/20129389fmF86mdUs8.png

Swagger UI還提供了我們可以測試API的介面
點下 1 的按鈕開始進行API的測試
2會列出此API需要的參數
3可以選擇Response要輸出的格式

https://ithelp.ithome.com.tw/upload/images/20200923/20129389rfH5HdQGZf.png
輸入完畢按下Excute便可看到結果

在測試API也時常需要設置權限才能測試,如果我們要在Swagger UI上使用權限設定,就必須另外進行設置,Swagger UI也提供了OAuth2ApiKey、以及JWT的做法,今天就以JWT作為範例示範。
以下為JWT驗證授權的設定範例:
Startup.ConfigureServices 中的

services.AddSwaggerDocument();

加入以下設置

services.AddSwaggerDocument(settings =>
{
    settings.AddSecurity("輸入身份認證Token", Enumerable.Empty<string>(), new NSwag.OpenApiSecurityScheme()
    {
        Description = "JWT認證 請輸入Bearer {token}",
        Name = "Authorization",
        In = NSwag.OpenApiSecurityApiKeyLocation.Header,
        Type = NSwag.OpenApiSecuritySchemeType.ApiKey
    });
    
    settings.OperationProcessors.Add(
        new AspNetCoreOperationSecurityScopeProcessor("JWT Token"));
});

In 是這個Token要設置在哪裡
Type 則是這個Security設置是什麼類型

輸入完畢之後就可以看到Swagger UI的畫面出現 Authorize 的按鈕
https://ithelp.ithome.com.tw/upload/images/20200924/20129389SfBCPDNuDm.png

按下去便可以設定Token內容了
https://ithelp.ithome.com.tw/upload/images/20200924/201293893PgV6i5EEK.png

透過 Swagger Editor 來產生程式碼

Windows的環境上可以安裝NSwagStudio來產生,詳情請看 NSwagStudio的github

雖然在macOS上無法安裝NSwagStudio,不過還是可以透過線上版的Swagger Editor 來做到程式碼產生的動作
以下是Swagger Editor的網址,選擇Live Demo來做使用。
https://swagger.io/tools/swagger-editor/

進入之後可以看到這個畫面
https://ithelp.ithome.com.tw/upload/images/20200924/20129389r2yjCqtjCI.png

接著我們從自己系統的Swagger UI取得定義API的JSON文件
https://ithelp.ithome.com.tw/upload/images/20200924/20129389anGUgjHecf.png

取得之後便可以複製貼上Swagger Editor的編輯器上,便能看到在我們的Swagger UI上顯示一樣的內容了。
接著可以選取 Generate Client
https://ithelp.ithome.com.tw/upload/images/20200924/20129389BPBx8NOUhF.png

選擇完之後,便會產出一份你所選擇語言的對應API的Client端程式碼,讓前端也能享受到規範統一帶來的便利!

參考文章
如何在 ASP․NET Core 3 完整設定 NSwag 與 OpenAPI v3 文件
使用 Swagger/OpenAPI 的 ASP.NET Core Web API 說明頁面
NSwag 與 ASP.NET Core 使用者入門


上一篇
[Day08] Restful API - 我與 ASP.NET Core 3 的 30天
下一篇
[Day10] 路由(Routing)- 我與 ASP.NET Core 3 的 30天
系列文
我與 ASP.NET Core 的 30天31
圖片
  直播研討會
圖片
{{ item.channelVendor }} {{ item.webinarstarted }} |
{{ formatDate(item.duration) }}
直播中

1 則留言

0
緯大啊緯大人
iT邦研究生 1 級 ‧ 2021-08-26 08:57:51

請問有產出API文件的範例嗎??
文中只有看到如何產出~
但不知道產出來 【清晰明瞭的REST API文件】到底長什麼樣子~

謝謝!

我要留言

立即登入留言