WebApi中使用swagger ui自動生成接口文檔

以前就寫到。最近正在使用webapi。這裏介紹一個實用的東西swageer ui
如今開發都是先後端分開。咱們這裏是給前端提供api。有時候對於一個api的描述，並不想專門寫一份文檔。很浪費時間。
swagger ui就是一個能整合到項目中讓api的註釋可以生成到一個網頁上。能簡單測試和給前端看。
開懟吧。

Step.1 Nuget安裝 
打開你的Nuget console，Install-Package Swashbuckle（要選擇哪一個項目）

ps.其實第一步安裝完了，你什麼不用作。運行起來，網址進入/swagger/ui/index就能看到你的那些api了（不帶註釋），不過沒達到咱們的預期效果——將註釋自動生成到文檔上。so，繼續往下看

Step.2 加上生成註釋的代碼
安裝以後會在App_Start文件夾中多了SwaggerConfig.cs類，該類中的Register()方法會在應用程序啓動的時候調用
裏面好多註釋，綠綠的，仍是選擇原諒他，刪掉吧，刪掉後就這剩下這些

public static void Register()
{
　　var thisAssembly = typeof(SwaggerConfig).Assembly;

　　GlobalConfiguration.Configuration
　　.EnableSwagger(c =>
　　{
　　　　c.SingleApiVersion("v1", "WebApplication1");
　　})
　　.EnableSwaggerUi(c =>
　　{

　　});
}

稍微改造一下，附加個註釋xml上去

public static void Register()
{
    var thisAssembly = typeof(SwaggerConfig).Assembly;

    GlobalConfiguration.Configuration
    .EnableSwagger(c =>
    {
        c.SingleApiVersion("v1", "WebApplication1");
        c.IncludeXmlComments(GetXmlCommentsPath());
    })
    .EnableSwaggerUi(c =>
    {    

    });
}

private static string GetXmlCommentsPath()
{
    return System.String.Format(@"{0}\bin\WebApplication1.XML", System.AppDomain.CurrentDomain.BaseDirectory);
}

Step.3 步驟2所必須的
啓用生成xml文檔，右擊項目文件屬性 bulid發佈——Output輸出（勾選XML文件）

其實swagger他就是依賴於build時生成的這個xml來自動生成註釋上頁面的

Step.4 完成啦，看看頁面

固然，個人追求不止這些，咱們來優化優化
首先，我比較喜歡將config都弄進WebApiConfig中就好，看起來比較清晰

public static class WebApiConfig
{
    public static void Register(HttpConfiguration config)
    {
        // Web API configuration and services

        // Web API routes
        config.MapHttpAttributeRoutes();

        config.Routes.MapHttpRoute(
            name: "DefaultApi",
            routeTemplate: "api/{controller}/{id}",
            defaults: new { id = RouteParameter.Optional }
        );

        config.RegistSwagger();//添加這個swagger的Regist
    }
    private static void RegistSwagger(this HttpConfiguration config)
    {
        config.EnableSwagger("docs/{apiVersion}/swagger", c =>
        {
            c.SingleApiVersion("v1", "WebApplication1");
            c.IncludeXmlComments(GetXmlCommentsPath());
        })
        .EnableSwaggerUi(c=> 
        {

        });
    }
    private static string GetXmlCommentsPath()
    {
        return $@"{AppDomain.CurrentDomain.RelativeSearchPath}\WebApplication1.XML";
    }
}

這個swagger的路徑也配一下吧，能夠自定義一下

private static void RegistSwagger(this HttpConfiguration config)
{
    config.EnableSwagger("docs/{apiVersion}/swagger", c =>
    {
        c.SingleApiVersion("v1", "WebApplication1");
        c.IncludeXmlComments(GetXmlCommentsPath());
    })
    .EnableSwaggerUi("apis/{*assetPath}");//本來進入的地址是/swagger/ui/index 這樣就能換地址成/apis/index 
}

這樣，咱們這基本的配置就能夠了，實現預期的效果——自動生成接口文檔