ASP.NET Core 2 學習筆記（十三）Swagger

Swagger也算是行之有年的API文件生成器，只要在API上使用C#的<summary />文件註解標簽，就可以產生精美的線上文件，並且對RESTful API有良好的支持。不僅支持生成文件，還支持模擬調用的交互功能，連Postman都不用打開就能測API。
本篇將介紹如何通過Swagger產生ASP.NET Core的RESTful API文件。

安裝套件

要在ASP.NET Core使用Swagger需要安裝Swashbuckle.AspNetCore套件。
通過過.NET Core CLI在項目文件夾執行安裝指令：

dotnet add package Swashbuckle.AspNetCore

註冊Swagger

在Startup.cs的ConfigureServices加入Swagger的服務及Middleware。如下：

using Swashbuckle.AspNetCore.Swagger;
// ...
public class Startup
{
    public void ConfigureServices(IServiceCollection services)
    {
        services.AddMvc()
                .AddJsonOptions(options => {
                    options.SerializerSettings.NullValueHandling = Newtonsoft.Json.NullValueHandling.Ignore;
                });

        services.AddSwaggerGen(c =>
        {
            c.SwaggerDoc(
                // name: 關係到 SwaggerDocument 的 URL 位置。
                name: "v1", 
                // info: 是用於 SwaggerDocument 版本信息的提示(內容非必填)。
                info: new Info
                {
                    Title = "RESTful API",
                    Version = "1.0.0",
                    Description = "This is ASP.NET Core RESTful API Sample.",
                    TermsOfService = "None",
                    Contact = new Contact { 
                        Name = "SnailDev", 
                        Url = "http://www.cnblogs.com/snaildev/" 
                    },
                    License = new License { 
                        Name = "CC BY-NC-SA 4.0", 
                        Url = "https://creativecommons.org/licenses/by-nc-sa/4.0/" 
                    }
                }
            );
        });
    }
    
    public void Configure(IApplicationBuilder app)
    {
        app.UseSwagger();
        app.UseSwaggerUI(c =>
        {
            c.SwaggerEndpoint(
                // url: 需配合 SwaggerDoc 的 name。 "/swagger/{SwaggerDoc name}/swagger.json"
                url: "/swagger/v1/swagger.json", 
                // name: 用於 Swagger UI 右上角選擇不同版本的 SwaggerDocument 提示名稱使用。
                name: "RESTful API v1.0.0"
            );
        });

        app.UseMvc();
    }
}

• AddSwaggerGen
  Swagger生成器是負責取得API的規格並產生SwaggerDocument物件。
• UseSwagger
  Swagger Middleware負責路由，提供SwaggerDocument物件。
  可以從URL查看Swagger產生器產生的SwaggerDocument物件。
  http://localhost:5000/swagger/v1/swagger.json
• UseSwaggerUI
  SwaggerUI是負責將SwaggerDocument物件變成漂亮的界面。
  預設URL：http://localhost:5000/swagger

API沿用ASP.NET Core 2 學習筆記（十二）REST-Like API的示常式序。

設定完成後，啟動網站就能開啟Swagger UI 了。下麵如下：

文件註解標簽

在API加入<summary />文件註解標簽。如下：

// ...
[Route("api/[controller]s")]
public class UserController : Controller
{
    /// <summary>
    /// 查詢使用者清單
    /// </summary>
    /// <param name="q">查詢使用者名稱</param>
    /// <returns>使用者清單</returns>
    [HttpGet]
    public ResultModel Get(string q) {
        // ...
    }
}　

再次打開Swagger，會發現沒有顯示說明，因為沒有設定.NET 的XML 文件目錄，所以Swagger 抓不到說明是正常的。

打開*.csproj，在<Project />區塊中插入以下代碼：

  <PropertyGroup Condition="'$(Configuration)|$(Platform)'=='Debug|AnyCPU'">
    <DocumentationFile>bin\Debug\netcoreapp2.0\Api.xml</DocumentationFile>
    <NoWarn>1591</NoWarn>
  </PropertyGroup>

以我示例的*.csproj內容如下：

<Project Sdk="Microsoft.NET.Sdk.Web">

  <PropertyGroup>
    <TargetFramework>netcoreapp2.0</TargetFramework>
  </PropertyGroup>

  <PropertyGroup Condition="'$(Configuration)|$(Platform)'=='Debug|AnyCPU'">
    <DocumentationFile>bin\Debug\netcoreapp2.0\Api.xml</DocumentationFile>
    <NoWarn>1591</NoWarn>
  </PropertyGroup>

  <ItemGroup>
    <Folder Include="wwwroot\" />
  </ItemGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.AspNetCore.All" Version="2.0.8" />
    <PackageReference Include="Swashbuckle.AspNetCore" Version="2.5.0" />
  </ItemGroup>

</Project>

然後在Swagger生成器設定讀取<DocumentationFile>指定的XML文件目錄位置：

// ...
public class Startup
{
    public void ConfigureServices(IServiceCollection services)
    {
        // ...
        services.AddSwaggerGen(c =>
        {
            // ...
            var filePath = Path.Combine(PlatformServices.Default.Application.ApplicationBasePath, "Api.xml");
            c.IncludeXmlComments(filePath);
        });
    }
}

返回格式

以RESTful API的例子來看，返回的格式都是JSON，所以可以直接在Controller加上[Produces("application/json")]表示返回的類型都是JSON，在Swagger的Response Content Type選項就會被鎖定只有application/json可以使用。如下：

// ...
[Route("api/[controller]s")]
[Produces("application/json")]
public class UserController : Controller
{
    // ...
}

返回類型

若有預期API在不同的HTTP Status Code時，會返回不同的對象，可以透過[ProducesResponseType(type)]定義返回的對象。在Swagger中就可以清楚看到該API可能會發生的HTTP Status Code及返回對象。例如：

// ...
[Route("api/[controller]s")]
[Produces("application/json")]
public class UserController : Controller
{
    /// <summary>
    /// 查詢使用者清單
    /// </summary>
    /// <param name="q">查詢使用者名稱</param>
    /// <returns>使用者清單</returns>
    [HttpGet]
    [ProducesResponseType(typeof(ResultModel<IEnumerable<UserModel>>), 200)]
    [ProducesResponseType(typeof(ResultModel<string>), 500)]
    public ResultModel<IEnumerable<UserModel>> Get(string q)
    {
        // ...
    }
}

執行結果

參考

ASP.NET Core Web API Help Pages using Swagger 
Swagger tools for documenting API's built on ASP.NET Core

老司機發車啦：https://github.com/SnailDev/SnailDev.NETCore2Learning