Swagger2引數使用相同物件展示不同引數的實現

2021-10-04 14:11:47 字數 2809 閱讀 8391

新框架的使用

在我們正常的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 與 ...