「NSwag」是 .net 下的描述 OpenAPI 好用工具

一、介紹

NSwag 是一個 .net、.net core 下的 Swagger / OpenAPI 2.0 和 3.0 的工具，使用 JOSN 去描述 RESTful web API。

二、Swagger

Swagger 是一個介面描述語言使用 JSON 去描述 RESTful API

三、開發環境

• 整合開發環境：Visual Studio 2019
• 語言：C#
• .net framework：4.6.2

四、Nuget

• NSwag.AspNet.Owin
• Microsoft.AspNet.WebApi.Owin

五、操作步驟

圖、建立 TestApiController.cs

• 原始碼

/// <summary>
/// TestApiController summary
/// </summary>
public class TestApiController : ApiController
{
    /// <summary>
    /// TestApi Get TestVm summary
    /// </summary>
    /// <param name="data"></param>
    /// <returns></returns>
    [HttpGet]
    public List<string> Get([FromUri]List<string> data) 
    {
        return data;
    }
}

圖、修改 Startup.cs

• 原始碼

var config = new HttpConfiguration();

app.UseSwaggerUi3(typeof(Startup).Assembly, settings =>
{
    settings.GeneratorSettings.DefaultUrlTemplate = "api/{controller}/{action}/{id?}";
});
app.UseWebApi(config);

config.MapHttpAttributeRoutes();
config.EnsureInitialized();

圖、修改 Web.config

• 修改 modules

<system.webServer>
    ...
    <modules runAllManagedModulesForAllRequests="true" />
</system.webServer>

• 修改 handlers，新增 NSwag 設定

<system.webServer>
    ...
    <handlers>
        ...
        <add name="NSwag" path="swagger" verb="*" type="System.Web.Handlers.TransferRequestHandler" preCondition="integratedMode,runtimeVersionv4.0" />
    </handlers>
</system.webServer>

圖、執行結果

六、完整原始碼

• TestApiController.cs

/// <summary>
/// TestApiController summary
/// </summary>
public class TestApiController : ApiController
{
    /// <summary>
    /// TestApi Get TestVm summary
    /// </summary>
    /// <param name="data"></param>
    /// <returns></returns>
    [HttpGet]
    public List<string> Get([FromUri]List<string> data) 
    {
        return data;
    }
}

• Startup.cs

public partial class Startup
{
    public void Configuration(IAppBuilder app)
    {
        ConfigureAuth(app);

        var config = new HttpConfiguration();

        app.UseSwaggerUi3(typeof(Startup).Assembly, settings =>
        {
            settings.GeneratorSettings.DefaultUrlTemplate = "api/{controller}/{action}/{id?}";
        });
        app.UseWebApi(config);

        config.MapHttpAttributeRoutes();
        config.EnsureInitialized();
    }
}

七、相關連結

1. 在「Visual Studio 2019 」使用 「NuGet」 安裝第三方套件
2. 使用「Visual Studio 2019」建置一個有 Mvc 和 Web Api 架構的網站

八、參考

1. NSwag
2. Middlewares
3. OWIN-Middleware