NetCore WebApi項目使用Swagger生成API交互文檔


開篇:

  現在項目的開發一般都采用前后端分離的模式,后端同學完成開發后需要給前端的同學提供詳細的API接口文檔說明,手動整理費事費力。那有沒有解放雙手的自動化工具呢?答案是肯定的。之前做.net webapi的時候使用的HelpPage來生成的API文檔,到netcore這里,就是我們今天要分享的Swagger,它可以根據代碼注釋自動生成API描述文檔,也可以通過配置生成交互式文檔實現在線接口測試。

 

關於這個swagger大兄弟:

  全稱:Swashbuckle.AspNetCore,開源項目,git地址:https://github.com/domaindrivendev/Swashbuckle.AspNetCore

 

目錄:

  1.基本使用

    1.1 安裝依賴

    1.2 startup配置

    1.3 swagger啟動配置

  2.進階使用

    2.1 接口描述

    2.2 返回類型描述

    2.3 忽略不生成到API文檔

    2.4 api分組管理

    2.5 多xml文檔配置

  3.擴展使用

    3.1 全局信息添加(作者、聯系人、許可信息等)

    3.2 默認折疊配置

 

一、基本使用

  1.1 安裝Swagger依賴

  第一種方式,程序包管理控制台:install-package Swashbuckle.AspNetCore

  

  第二種方式,Nuget包管理中搜索 Swashbuckle.AspNetCore

  

 

 

  1.2 startup配置

  要使用swagger生成文檔,我們需要在startup的ConfigureServices 和 Configure中對其進行中間件配置

  • 在ConfigureServices中注冊swagger生成器

 

1 // 注冊swagger生成器,定義一個或多個文檔,多個文檔后邊會講到
2 services.AddSwaggerGen(c =>
3 {
4     c.SwaggerDoc("v1", new OpenApiInfo { Title = "曦昊-API說明文檔", Version = "v1" });
5 });

 

  • 在Configure中啟用中間件配置
 // 啟用中間件以將生成的 Swagger 公開為JSON終結點
 app.UseSwagger();
 // 啟用swagger-ui 中間件,指定 Swagger JSON 終結點,以來公開交互式文檔
 app.UseSwaggerUI(c =>
 {
    c.SwaggerEndpoint("/swagger/v1/swagger.json", "API說明文檔 V1");
 });

  至此,swagger的基本配置完成,我們可以啟動應用程序,輸入/swagger訪問看看啦

  

  我們可以看到swagger已經自動幫我們生成了項目的api接口描述文檔

  

  1.3 swagger啟動配置

  完成上邊的步驟后,我們已經可以啟動瀏覽/swagger訪問我們的Rest Apis文檔了,但是每次啟動再輸入swagger也太麻煩了,接下來我們把swagger設置為我們的啟動地址

  文件:Properties - > launchSettings.json

  將標注位置改為“swagger”

  

 

  再次啟動,直接進入了我們的swagger文檔頁面。

 

二、進階使用

   2.1 接口描述

  上邊已經提過swagger會根據我們的注釋生成文檔描述信息,但並不是我們添加了注釋就可以的,想要swagger正常顯示我們的備注信息,除了添加注釋信息外,我們還要為swagger配置包含xml描述信息

  首先按照我們平常的注釋方式為接口添加注釋

  

 

 

 

  其次,為我們的項目配置輸出xml文件(項目右鍵--屬性--生成--輸出)

  

 

 

   最后在startup的ConfigureServices中配置swagger包含xml描述信息

    

    // 配置從xml文檔中獲取描述信息
    // 路徑我們獲取的項目路徑+startup命名空間(也可以直接寫生成的xml名稱)
    var filePath = Path.Combine(System.AppContext.BaseDirectory, typeof(Startup).Assembly.GetName().Name + ".xml");
    c.IncludeXmlComments(filePath);
View Code

  ok,現在我們啟動調試進入swaggerUI,我們會看到swagger已經顯示出了我們自定義的注釋信息

  

 

  2.2 返回類型描述

  當我們寫的接口已IActionResult為返回類型的時候,我們會發現swagger的Responses下並沒有為我們生成返回信息描述,因為它並不知道我們具體要返回的是什么形式的數據

  例如,我們新寫一個分頁接口:

      

 

 

   我們可以看到沒有任何的返回信息描述,那怎么辦呢?這里我們就要用到swagger的ProducesResponseType特性來告訴swagger我們的返回結構

  

 

 

 

 

 

   再次啟動調試,我們發現在Responses這一模塊已經正確顯示了我們的PageList描述信息。

 

  細心的可能會發現我們在使用ProducesResponseType的時候除了給了它一個type,還給了一個200,這是啥意思呢?

  這個200的意思就是響應狀態200的時候我給你返回這么一個結構的數據,那是不是說我們可以定義不同響應狀態不同數據結構呢?答案是肯定的。ProducesResponseType是可以多次標記的,你只需要為其他狀態按照上邊的方式添加返回結構標記即可

  

  2.3 忽略不生成到API文檔

  有些時候我們需要向文檔的閱讀者隱藏部分的接口信息,這個時候我們就會用到ApiExplorerSettings特性

  在我們需要隱藏的接口標記  [ApiExplorerSettings(IgnoreApi = true)]  即可

 

  2.4 api分組管理

  當我們的接口過多想要拆分顯示,或我們根據不同大類進行區分(系統操作、業務操作...),或我們要分多個版本等等,我們就需要用到分組這個操作,實際上分組就是為swagger生成多個文檔,上操作:

  第一步,為swagger添加一個新的文檔(startup -- > ConfigureServices)

  

 

    第二步,為swagger添加一個對應的json終結點

  

 

   第三步,為控制器或action方法添加標記 [ApiExplorerSettings(GroupName = "v2")] ,groupName設置的是要在哪一組中顯示,這里是區分大小寫的,要跟上述設置中保持一致

   然后就可以在swagegrUI界面的右上角切換不同的文檔了

  

 

  2.5 多xml文檔配置

  常用場景:跨程序集顯示注釋信息

  swagger我們默認配置的是加載當前程序生成的xml,我們只需要為為其它程序集配置輸出xml,並在services.AddSwaggerGen中配置加載改xml文件即可

  例如:

  

 

    但是,如果有多個程序集需要配置,這里是不是會有很多的配置項,並且每加一個程序集我們就要寫一遍,即不方便又造成代碼的臃腫。ok,接下來我們進行一下改版

  首先,我們把所有的xml生成到一個目錄下,比如當前應用根目錄的docs:

  

 

   

 

  然后我們在swagger設置xml文檔的地方改為以下方式  

    // 獲取自定義的xml目錄   
    var xmlPath = Path.Combine(System.AppContext.BaseDirectory, "Docs");
    DirectoryInfo dir = new DirectoryInfo(xmlPath);
    // 獲取目錄下的所有xml文件,並設置為swagger文檔包含文件
    dir.GetFiles("*.xml").ToList().ForEach(u =>
    {
         c.IncludeXmlComments(u.FullName, true);
    })

  ok,再次啟動程序,我們會發現,XH.Core下Model對象的描述信息也有了~

 

 

 三、擴展使用

  3.1 全局信息添加(作者、聯系人、許可信息等)

  這些信息的配置是在services.AddSwaggerGen下進行配置,如下:

  

 

  運行程序,顯示如下

  

 

  

  3.2 默認折疊配置

  當接口慢慢變多,你想進入swagger頁面后能非常清晰的瀏覽controller級目錄,你會需要這個配置  

    app.UseSwaggerUI(c =>
    {
         c.SwaggerEndpoint("/swagger/v1/swagger.json", "API說明文檔 V1");
         c.SwaggerEndpoint("/swagger/v2/swagger.json", "API說明文檔 V2");
         c.DocExpansion(DocExpansion.None); // 全部折疊
    });

  如果想隱藏掉Schemas,使用 c.DefaultModelsExpandDepth(-1) 設置即可,位置同上

  

  

  ok,羅里吧嗦碼了這些,文本粗糙,請多包涵,有問題歡迎指出,謝過!

   

 

 

  


免責聲明!

本站轉載的文章為個人學習借鑒使用,本站對版權不負任何法律責任。如果侵犯了您的隱私權益,請聯系本站郵箱yoyou2525@163.com刪除。



 
粵ICP備18138465號   © 2018-2025 CODEPRJ.COM