開篇:
現在項目的開發一般都采用前后端分離的模式,后端同學完成開發后需要給前端的同學提供詳細的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);
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,羅里吧嗦碼了這些,文本粗糙,請多包涵,有問題歡迎指出,謝過!