Abp集成Swagger的最佳實踐

 

1.在項目中添加nuget包 Abp.Web.Api.SwaggerTool

2.在項目Abp模塊的DependsOn添加AbpWebApiSwaggerToolModule

Run It,啟動項目，訪問/swagger/ui/index 就打開熟悉的swagger-ui界面，項目中webapi和動態Api的接口都出現了。

 

 Abp.Web.Api.SwaggerTool作為swagger的增強包，內部實現了很多有用的功能並提供了一些最佳實踐，用戶無需在意Swagger的集成問題。

項目源碼https://github.com/yuzukwok/Abp.Web.Api.SwaggerTool 大家可以提出issue 或者fork下

 

 

功能介紹

1.遠程代理生成

我們可以根據swagger文檔所描述的Api元信息生成訪問這些Api的遠程代理，目前支持Csharp的WebApiClient，Jquery或者AngularJS等代碼。

用戶訪問以下endpoint獲取代理的代碼

/swagger/proxy/CSharp
/swagger/proxy/JQueryCallbacks
/swagger/proxy/JQueryPromises
/swagger/proxy/AngularJS
/swagger/proxy/Angular2

2.轉換swagger文檔為POSTMAN支持的導入格式，比POSTMAN自帶的導入功能有更強的通用性

訪問點：/swagger/postman

按文件夾分類，支持中文注釋，POST接口自動生成了sample數據

 

3. 可以直接在swagger-ui上搜索接口，目前只支持搜索api地址

/swagger/docs/{apiVersion}/{key to search by path}

4.6種的swagger-ui樣式,擺脫默認的swagger-ui

https://github.com/ostranme/swagger-ui-themes

5.強化Swashbuckle：優化枚舉顯示，自動使用Display特性的文本，WebApiController類上加DisplayName特性可以在swagger-ui上顯示Controller的注釋

 

配置文件說明

類庫采用lts.Configuation作為配置文件約定，默認無需配置文件

在網站根目錄配置.config 文件夾，新建一個SwaggerToolSettings.json 文件 ，文件內容如下

{
  "enable": true, //是否啟用swagger集成
  "theme": "flattop", //主題名稱 flattop，muted，newspaper，outline，monokai，feeling-blue
"HideAbpAutogeneratedApi": false, //是否隱藏Abp框架生成的Api接口
"HideDocPathAttributeName": "XX", //Api上標注此特性的話，則不在swagger中生成
"HideDocPaths": ["path1"],//Api中包含這些字符，則不在swagger中生成
  "CSharpGen": {
    "ClassName": "ApiClient", //C#代理生成的類名
    "Namespace": "ApiServices" //C#代理生成的命名空間
  },
  "TypeScriptGen": {
    "ClassName": "Client", //JS代理生成的類名
    "Namespace": "ApiServices" //JS代理生成的命名空間
  },
  "PostmanGen": {
    "name": "ApiServices" //名稱
  },
  "XmlCommentFiles": ["xxx.xml"]//xml注釋的文件名


}