Swagger實現API文檔功能

介紹：

wagger也稱爲Open API，Swagger從API文檔中手動完成工做，並提供一系列用於生成，可視化和維護API文檔的解決方案。簡單的說就是一款讓你更好的書寫API文檔的框架。

咱們爲何選擇swagger，如今的網站開發結果愈來愈注重先後端的分離，好比之前的webFrom到如今的mvc模式都是爲了這個先後端的分離。就算再如何的分離實現，也是不可避免的要進行數據交互的，那麼接口的重要性就提現出來了。他成了前端和後端交互的重要途徑，API文檔也所以成了前端開發人員與後端開發人員的重要紐帶。全部咱們有一個API文檔框架豈不是美哉。

Swashbuckle有三個主要組件：

Swashbuckle.AspNetCore.Swagger：Swagger對象模型和中間件，將SwaggerDocument對象公開爲JSON端點。
Swashbuckle.AspNetCore.SwaggerGen：一種Swagger生成器，可SwaggerDocument直接從路由，控制器和模型構建對象。它一般與Swagger端點中間件結合使用，以自動公開Swagger JSON。
Swashbuckle.AspNetCore.SwaggerUI：Swagger UI工具的嵌入式版本。它將Swagger JSON解釋爲構建豐富的，可定製的Web API功能描述體驗。它包括用於公共方法的內置測試線束。

開始使用：

首先咱們要有一個WebAPI項目，假設咱們已經建立好了，不懂WebAPI如何建立的請看這篇文章：建立簡單的WebAPI

好了如今咱們已經有了項目那咱們就開始添加引用吧：

Nuget 命令行 ：Install-Package Swashbuckle.AspNetCore

添加並配置Swagger中間件：

而後配置Startup.cs 文件中的ConfigureServices方法，固然首先不要忘記引用一下using Swashbuckle.AspNetCore.Swagger命名空間，否則info類會報錯。

public void ConfigureServices(IServiceCollection services)
        {
            services.AddMvc()
                    .SetCompatibilityVersion(CompatibilityVersion.Version_2_1)
                    .AddJsonOptions(options =>
                                    options.SerializerSettings.ContractResolver =
                                    new Newtonsoft.Json.Serialization.DefaultContractResolver());//JSON首字母小寫解決;

            services.AddSwaggerGen(options =>
            {
                options.SwaggerDoc("v1", new Info
                {
                    Version = "v1",
                    Title = " API 文檔"
                });

            });
        }

 而後在Configure方法中添加：

//容許中間件爲JSON端點服務生成的Siggg
            app.UseSwagger();
            //使中間件可以服務於輕量級用戶界面（HTML、JS、CSS等），並指定SWAGJER JSON端點
            app.UseSwaggerUI(c =>
            {
                c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
                // 要在應用程序的根處提供Swagger UI ，請將該RoutePrefix屬性設置爲空字符串
                c.RoutePrefix = string.Empty;
            });

啓動效果：

這樣就能夠啓動了，配置好以上就是一個最簡單的api文檔示例了。首先你能夠訪問：http://localhost:<port>/swagger/v1/swagger.json 這個網址看到端點生成的文檔。

固然你想看到的是這個：http://localhost:<port>/swagger  ，你輸入這個網址也能夠，固然我把他配置成了根節點，這樣直接啓動根節點就是該頁面。主要是上面代碼中的： c.RoutePrefix = string.Empty這句代碼。

 擴展一些顯示：

咱們能夠擴展一些附加信息，好比做者，許可證，服務條款等。傳遞給該AddSwaggerGen方法的配置：

//Swagger生成器添加到方法中的服務集合中
            services.AddSwaggerGen(options =>
            {
                options.SwaggerDoc("v1", new Info
                {
                    Version = "v1",
                    Title = " API 文檔",
                    Description = "這是一個示例webapi文檔",
                    //服務條款
                    TermsOfService = "None",
                    //做者信息
                    Contact = new Contact
                    {
                        Name = "ybf",
                        Email = string.Empty,
                        Url = "http://www.cnblogs.com/yanbigfeg/"
                    },
                    //許可證
                    License = new License
                    {
                        Name = "許可證名字",
                        Url = "http://www.cnblogs.com/yanbigfeg/"
                    }
                });

            });

顯示結果

 xml註釋：

啓用XML註釋可爲未記錄的公共類型和成員提供調試信息。未記錄的類型和成員由警告消息指示。配置Swagger以使用生成的XML文件。

在咱們實現前先設置一下項目屬性：

 

這樣就能夠在項目bin下生成xml文件了。下面進行代碼配置啓用，仍是在Startup類中的ConfigureServices方法中，在咱們剛纔配置的下面在增長如下代碼：

// 設置SWAGER JSON和UI的註釋路徑。
                var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
                var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
                options.IncludeXmlComments(xmlPath);

使用反射主要是爲了生成一個與項目文件名相同的xml文件。第二部而後是配置文件路徑。這些配置好了之後。咱們就能夠把方法或者類的三道斜槓（「///」）的註釋添加到動做。咱們來看一下效果。

代碼

界面：

 

 

注意哦，就是開啓這個功能，項目會自動檢測那些方法或者類沒有註釋，會給出警告。

 

取消警告小技巧：

固然咱們也能夠取消掉：咱們在我的.csproj文件中使用分號分隔來取消警告信息：

<PropertyGroup Condition="'$(Configuration)|$(Platform)'=='Debug|AnyCPU'">
    <DocumentationFile>bin\Debug\netcoreapp2.1\SwaggerTest.xml</DocumentationFile>
    <GenerateSerializationAssemblies>On</GenerateSerializationAssemblies>
    <NoWarn>1701;1702;1705;1591</NoWarn>
  </PropertyGroup>

這樣就不會有警告提示了。

描述相應類型：

接口使用者最關心的就是接口的返回內容和相應類型啦。下面展現一下201和400一個簡單例子：

咱們須要在咱們的方法上添加：[ProducesResponseType(201)][ProducesResponseType(400)]

而後添加相應的狀態說明：<response code="201">返回value字符串</response><response code="400">若是id爲空</response>

最終代碼應該是這個樣子：

  View Code

運行起來咱們看一下結果：

 本例源碼下載：SwaggerTest.rar

傳送門：

WebApi系列文章介紹如何使用WebAPI：

• WebAPI——建立簡單的webApi（一）
• WebAPI——如何WebAPI發佈（二）
• WebAPI——API的訪問控制IdentityServer4（三。待完成）
• WebAPI——使用swagger實現API文檔功能（四）