新框架的使用
在我們正常的spring web框架下請求引數與響應引數使用的有許多相同的物件,當我們引入swagger2框架後,每個介面的引數(請求/響應)都會包含所有的字段。
有人也許使用過@jsonignoreproperties或@jsonignore進行引數的排除,這些註解有乙個弊端,會影響所有的json序列化問題,並且所有使用此引數物件的介面都會排除使用該註解的字段。
還有一種做法是每個介面引數都使用單獨的vo類,這種方式其中乙個問題是專案中存在著大量的vo類來適應文件,並且vo類進入專案後需要進行單獨轉換為對應的業務需要的物件,如果參數量或層級比較大的話,此轉換工作量比較大,並且與專案的耦合性也是比較高的。
經歷了種種方案後,作者的做法是使用註解進行分類引數。接下來我們看一下具體的使用方式。
目前擴充套件的swagger2版本為:2.7.0、2.8.0、2.9.1、2.9.2
對應擴充套件的最新版本為:2.7.0-1-beta4、2.8.0-1-beta2、2.9.1-1-beta2、2.9.2-1-beta2
接下來以2.7.0進行舉例
由於swagger2的版本增強的方式不同,所以我定義的版本與swagger2的版本是一一對應的。例如:swagger2的版本為2.7.0,對應的版本為2.7.0-x-x方式。
預設引入springfox-swagger2-plus專案時自動引入swagger2對應的版本. springfox-swagger-ui也會自動被引入.
>
>
cn.weiguangfugroupid
>
>
springfox-swagger2-plusartifactid
>
>
2.7.0-1version
>
dependency
>
其他專案管理工具(gradle groovy等)對接入口
此配置為了適應配置檔案方式的profile, 可以配置停用線上swagger2的增強
# 此配置標誌著開啟增強, 目的是為了可以遮蔽線上swagger2增強.
# 不編輯此配置或者值為enable: false則不開啟swagger2增強.
swagger
:plus
:enable
:true
僅增加@enableswagger2plus註解在原swagger2的配置類上即可,其他配置與swager2原配置相同。
/**
* @enableswagger2plus註解標誌著開啟swagger2plus,
* 此註解同時開啟swagger2的註解.
*/@configuration
@enableswagger2plus
public
class
swagger2config
}
/**
* @apiplus配置並且設定value=true表示開啟當前controller的api增強
*/@restcontroller
(value =
"/swagger2/plus"
)@apiplus
(value =
true
)@api
("swagger2plus測試類"
)public
class
swagger2pluscontroller
* 3. responseexecution: 響應執行方式 參見
*/("/demo"
)@apioperation
("swagger2plus測試方法"
)@apigroup
(groups = swagger2plusgroups.demo.
class
, responseexecution = apiexecutionenum.exclude)
public swagger2plus demo
(@requestbody swagger2plus swagger2plus)
}
@apimodel
("swagger2增強物件"
)public
class
swagger2plus
)@apiresponseexclude
(groups =
)@apirequestfieldrequired
(groups =
)private string name;
@apimodelproperty
("版本"
)@apirequestinclude
(groups =
)@apiresponseexclude
(groups =
)private string version;
@apimodelproperty
("子swagger2增強物件"
2.7.0-1版本的目前開始新增字段是否必填的功能, 目前測試中, 等穩定後其他版本也會陸續上線.
Swagger2使用記錄
configuration public class swagger2 private apiinfo apiinfo enableswagger2 public static void main string args io.springfox springfox swagger2 2.9.2 i...
swagger2的簡單使用
優點 可以生成文件形式的api並提供給不同的團隊使用 便於自己單測 無需過多冗餘的word文件,這一點很重要,因為我在工作中就遇到這麼乙個情況,由於開發使用的文件和最新文件版本導致不一致,導致後期很煩人 使用swagger流程 1.引入pom依賴 io.springfox springfox swa...
swagger2 常用註解的使用
一 api 效果 api註解放在類上面,這裡的value是沒用的,tags表示該controller的介紹。二 apioperation 效果 apioperation註解用於放在方法上面,其中value是該類的簡短的敘述,notes一般是該方法的詳細描述。三 apiimplicitparam 與 ...