SpringBoot中使用Knife4J的解決方案

第SpringBoot中使用Knife4J的解決方案目錄一、引入依賴二、創(chuàng)建配置類三、常用注解3-1@Api3-1-1@Api注解的常用屬性，如下：3-1-2@Api注解的不常用屬性，如下：3-2@ApiOperation3-2-1@ApiOperation注解的常用屬性，如下：3-2-2@ApiOperation注解的不常用屬性，如下：3-3@ApiImplicitParam3-3-1@ApiImplicitParam注解的常用屬性，如下：3-3-2@ApiImplicitParam注解的不常用屬性，如下：3-4@ApiModel3-4-1@ApiModel注解的常用屬性，如下：3-5@ApiModelProperty3-5-1@ApiModelProperty注解的常用屬性，如下：3-5-2@ApiModelProperty注解的不常用屬性，如下：3-6@ApiResponse四、配置JavaBean五、配置Controller六、接口文檔預(yù)覽knife4j是為JavaMVC框架集成Swagger生成Api文檔的增強(qiáng)解決方案。

knife4j的前身是swagger-bootstrap-ui，為了契合微服務(wù)的架構(gòu)發(fā)展，由于原來(lái)swagger-bootstrap-ui采用的是后端Java代碼+前端Ui混合打包的方式,在微服務(wù)架構(gòu)下顯的很臃腫，因此項(xiàng)目正式更名為knife4j。knife4j官方網(wǎng)址：knife4j

一、引入依賴

Knife4J官網(wǎng)：

/

快速開始：/docs/quick-start

!--引入Knife4j的官方start包,Swagger2基于Springfox2.10.5項(xiàng)目--

dependency

groupIdcom.github.xiaoymin/groupId

!--使用Swagger2--

artifactIdknife4j-spring-boot-starter/artifactId

version2.0.9/version

/dependency

二、創(chuàng)建配置類

創(chuàng)建config包，在其中新建一個(gè)配置類：

@Configuration

@EnableSwagger2WebMvc

publicclassKnife4jConfiguration{

@Bean(value="dockerBean")

publicDocketdockerBean(){

//指定使用Swagger2規(guī)范

Docketdocket=newDocket(DocumentationType.SWAGGER_2)

.apiInfo(newApiInfoBuilder()

//描述字段支持Markdown語(yǔ)法

.description("#寫一個(gè)簡(jiǎn)要的描述")

.termsOfServiceUrl("/")

.contact("可以寫作者的信息")

.version("1.0")

.build())

//分組名稱

.groupName("用戶服務(wù)")

.select()

//這里指定Controller掃描包路徑

.apis(RequestHandlerSelectors.basePackage("com.xueou.boot.controller"))

.paths(PathSelectors.any())

.build();

returndocket;

最重要的配置還是：指定Controller掃描包路徑contact

官方是棄用了直接傳字符串的這個(gè)設(shè)置方法，改用傳入一個(gè)Contact類，看一下源碼可以發(fā)現(xiàn)該類的結(jié)構(gòu)（內(nèi)容更豐富了：姓名、郵箱、URL連接）

三、常用注解

3-1@Api

@Api注解，添加在Controller類上，標(biāo)記它作為Swagger文檔資源。

3-1-1@Api注解的常用屬性，如下：

tags屬性：用于控制API所屬的標(biāo)簽列表。[]數(shù)組，可以填寫多個(gè)?？梢栽谝粋€(gè)Controller上的@Api的tags屬性，設(shè)置多個(gè)標(biāo)簽，那么這個(gè)Controller下的API接口，就會(huì)出現(xiàn)在這兩個(gè)標(biāo)簽中。如果在多個(gè)Controller上的@Api的tags屬性，設(shè)置一個(gè)標(biāo)簽，那么這些Controller下的API接口，僅會(huì)出現(xiàn)在這一個(gè)標(biāo)簽中。本質(zhì)上，tags就是為了分組API接口，和Controller本質(zhì)上是一個(gè)目的。所以絕大數(shù)場(chǎng)景下，我們只會(huì)給一個(gè)Controller一個(gè)唯一的標(biāo)簽。

3-1-2@Api注解的不常用屬性，如下：

produces屬性：請(qǐng)求請(qǐng)求頭的可接受類型(Accept)。如果有多個(gè)，使用,分隔。consumes屬性：請(qǐng)求請(qǐng)求頭的提交內(nèi)容類型(Content-Type)。如果有多個(gè)，使用,分隔。protocols屬性：協(xié)議，可選值為http、https、ws、wss。如果有多個(gè)，使用,分隔。authorizations屬性：授權(quán)相關(guān)的配置，[]數(shù)組，使用@Authorization注解。hidden屬性：是否隱藏，不再API接口文檔中顯示。

@Api注解的廢棄屬性，不建議使用，有value、description、basePath、position。

3-2@ApiOperation

@ApiOperation注解，添加在Controller方法上，標(biāo)記它是一個(gè)API操作。

3-2-1@ApiOperation注解的常用屬性，如下：

value屬性：API操作名。notes屬性：API操作的描述。

3-2-2@ApiOperation注解的不常用屬性，如下：

tags屬性：和@API注解的tags屬性一致。nickname屬性：API操作接口的唯一標(biāo)識(shí)，主要用于和第三方工具做對(duì)接。httpMethod屬性：請(qǐng)求方法，可選值為GET、HEAD、POST、PUT、DELETE、OPTIONS、PATCH。因?yàn)镾wagger會(huì)解析SpringMVC的注解，所以一般無(wú)需填寫。produces屬性：和@API注解的produces屬性一致。consumes屬性：和@API注解的consumes屬性一致。protocols屬性：和@API注解的protocols屬性一致。authorizations屬性：和@API注解的authorizations屬性一致。hidden屬性：和@API注解的hidden屬性一致。response屬性：響應(yīng)結(jié)果類型。因?yàn)镾wagger會(huì)解析方法的返回類型，所以一般無(wú)需填寫。responseContainer屬性：響應(yīng)結(jié)果的容器，可選值為L(zhǎng)ist、Set、Map。responseReference屬性：指定對(duì)響應(yīng)類型的引用。這個(gè)引用可以是本地，也可以是遠(yuǎn)程。并且，當(dāng)設(shè)置了它時(shí)，會(huì)覆蓋response屬性。說(shuō)人話，就是可以忽略這個(gè)屬性，哈哈哈。responseHeaders屬性：響應(yīng)頭，[]數(shù)組，使用@ResponseHeader注解。code屬性：響應(yīng)狀態(tài)碼，默認(rèn)為200。extensions屬性：拓展屬性，[]屬性，使用@Extension注解。ignoreJsonView屬性：在解析操作和類型，忽略JsonView注釋。主要是為了向后兼容。

@ApiOperation注解的廢棄屬性，不建議使用，有position。

3-3@ApiImplicitParam

@ApiImplicitParam注解，添加在Controller方法上，聲明每個(gè)請(qǐng)求參數(shù)的信息。

3-3-1@ApiImplicitParam注解的常用屬性，如下：

name屬性：參數(shù)名。value屬性：參數(shù)的簡(jiǎn)要說(shuō)明。required屬性：是否為必傳參數(shù)。默認(rèn)為false。dataType屬性：數(shù)據(jù)類型，通過字符串String定義。dataTypeClass屬性：數(shù)據(jù)類型，通過dataTypeClass定義。在設(shè)置了dataTypeClass屬性的情況下，會(huì)覆蓋dataType屬性。推薦采用這個(gè)方式。paramType屬性：參數(shù)所在位置的類型。有如下5種方式：

path值：對(duì)應(yīng)SpringMVC的@PathVariable注解。

【默認(rèn)值】query值：對(duì)應(yīng)SpringMVC的@PathVariable注解。

body值：對(duì)應(yīng)SpringMVC的@RequestBody注解。

header值：對(duì)應(yīng)SpringMVC的@RequestHeader注解。

form值：Form表單提交，對(duì)應(yīng)SpringMVC的@PathVariable注解。

絕大多數(shù)情況下，使用query值這個(gè)類型即可。

example屬性：參數(shù)值的簡(jiǎn)單示例。examples屬性：參數(shù)值的復(fù)雜示例，使用@Example注解。

3-3-2@ApiImplicitParam注解的不常用屬性，如下：

defaultValue屬性：默認(rèn)值。allowableValues屬性：允許的值。如果要設(shè)置多個(gè)值，有兩種方式：

數(shù)組方式，即{value1,value2,value3}。例如說(shuō)，{1,2,3}。

范圍方式，即[value1,value2]或[value1,value2)。例如說(shuō)[1,5]表示1到5的所有數(shù)字。如果有無(wú)窮的，可以使用(-infinity,value2]或[value1,infinity)。

allowEmptyValue屬性：是否允許空值。allowMultiple屬性：是否允許通過多次傳遞該參數(shù)來(lái)接受多個(gè)值。默認(rèn)為false。type屬性：搞不懂具體用途，對(duì)應(yīng)英文注釋為Addstheabilitytooverridethedetectedtype。readOnly屬性：是否只讀。format屬性：自定義的格式化。collectionFormat屬性：針對(duì)Collection集合的，自定義的格式化。

當(dāng)我們需要添加在方法上添加多個(gè)@ApiImplicitParam注解時(shí)，可以使用@ApiImplicitParams注解中添加多個(gè)。

3-4@ApiModel

@ApiModel注解，添加在POJO類，聲明POJO類的信息。而在Swagger中，把這種POJO類稱為Model類。所以，我們下文就統(tǒng)一這么稱呼。

3-4-1@ApiModel注解的常用屬性，如下：

value屬性：Model名字。description屬性：Model描述。

3-4-2@ApiModel注解的不常用屬性，如下：

parent屬性：指定該Model的父Class類，用于繼承父Class的Swagger信息。subTypes屬性：定義該Model類的子類Class們。discriminator屬性：搞不懂具體用途，對(duì)應(yīng)英文注釋為Supportsmodelinheritanceandpolymorphism.reference屬性：搞不懂具體用途，對(duì)應(yīng)英文注釋為Specifiesareferencetothecorrespondingtypedefinition,overridesanyothermetadataspecified

3-5@ApiModelProperty

@ApiModelProperty注解，添加在Model類的成員變量上，聲明每個(gè)成員變量的信息。

3-5-1@ApiModelProperty注解的常用屬性，如下：

value屬性：屬性的描述。dataType屬性：和@ApiImplicitParam注解的dataType屬性一致。不過因?yàn)锧ApiModelProperty是添加在成員變量上，可以自動(dòng)獲得成員變量的類型。required屬性：和@ApiImplicitParam注解的required屬性一致。example屬性：@ApiImplicitParam注解的example屬性一致。

3-5-2@ApiModelProperty注解的不常用屬性，如下：

name屬性：覆蓋成員變量的名字，使用該屬性進(jìn)行自定義。allowableValues屬性：和@ApiImplicitParam注解的allowableValues屬性一致。position屬性：成員變量排序位置，默認(rèn)為0。hidden屬性：@ApiImplicitParam注解的hidden屬性一致。accessMode屬性：訪問模式，有AccessMode.AUTO、AccessMode.READ_ONLY、AccessMode.READ_WRITE三種，默認(rèn)為AccessMode.AUTO。reference屬性：和@ApiModel注解的reference屬性一致。allowEmptyValue屬性：和@ApiImplicitParam注解的allowEmptyValue屬性一致。extensions屬性：和@ApiImplicitParam注解的extensions屬性一致。

@ApiModelProperty注解的廢棄屬性，不建議使用，有readOnly。

3-6@ApiResponse

在大多數(shù)情況下，我們并不需要使用@ApiResponse注解，因?yàn)槲覀儠?huì)類似UserController#get(id)方法這個(gè)接口，返回一個(gè)Model即可。

@ApiResponse注解，添加在Controller類的方法上，聲明每個(gè)響應(yīng)參數(shù)的信息。@ApiResponse注解的屬性，基本已經(jīng)被@ApiOperation注解所覆蓋，如下：message屬性：響應(yīng)的提示內(nèi)容。code屬性：和@ApiOperation注解的code屬性一致。response屬性：和@ApiOperation注解的response屬性一致。reference屬性：和@ApiOperation注解的responseReference屬性一致。responseHeaders屬性：和@ApiOperation注解的responseHeaders屬性一致。responseContainer屬性：和@ApiOperation注解的responseContainer屬性一致。examples屬性：和@ApiOperation注解的examples屬性一致。

當(dāng)我們需要添加在方法上添加多個(gè)@ApiResponse注解時(shí)，可以使用@ApiResponses注解中添加多個(gè)。

四、配置JavaBean

主要用于返回參數(shù)、或是接收參數(shù)的時(shí)候進(jìn)行說(shuō)明。

@Getter

@Setter

@ToString

@NoArgsConstructor

@ApiModel(value="輪播圖對(duì)象",description="")

publicclassBannerimplementsSerializable{

@ApiModelProperty(value="id",example="1")

@TableId(value="id",type=IdType.AUTO)

privateIntegerid;

@ApiModelProperty(value="圖像鏈接",example="https://xxx/xxx.png")

privateStringimgUrl;

@ApiModelProperty(value="標(biāo)題",example="這是一個(gè)標(biāo)題喲~")

privateStringtitle;

我自己用的時(shí)候，又封裝了一層，設(shè)置了幾個(gè)JavaBean用于包裝返回的響應(yīng)結(jié)果：

分別用于返回單個(gè)數(shù)據(jù)、數(shù)據(jù)列表，同時(shí)附帶上狀態(tài)碼和說(shuō)明信息。

@Data

@ToString

@AllArgsConstructor

@NoArgsConstructor

publicabstractclassRBean{

@ApiModelProperty(value="響應(yīng)碼",

position=0,

example="200",

notes="200:成功；500：失?。?)

privateIntegercode;

@ApiModelProperty(value="響應(yīng)說(shuō)明",position=1,example="xx數(shù)據(jù)獲取成功。")

privateStringmsg;

//=====================

@EqualsAndHashCode(callSuper=true)

@Data

@ToString

@AllArgsConstructor

@NoArgsConstructor

publicclassROneBeanTextendsRBean{

@ApiModelProperty(value="數(shù)據(jù)項(xiàng)",position=2)

privateTdata;

//=======================

@EqualsAndHashCode(callSuper=true)

@Data

@ToString

@AllArgsConstructor

@NoArgsConstructor

publicclassRListBeanTextendsRBean{

@ApiModelProperty(value="數(shù)據(jù)列表",position=2)

privateListTdata;

五、配置Controller

潦草的寫幾個(gè)接口

@Api(tags="首頁(yè)模塊")

@RestController

publicclassIndexController{

@Resource

IBannerServiceiBannerService;

@ApiOperation(value="域名直接轉(zhuǎn)接口文檔",hidden=true)

@GetMapping("/")

publicvoidtoDoc(HttpServletResponseresponse)throwsIOException{

response.sendRedirect("/doc.html");

@ApiOperation("新增輪播圖數(shù)據(jù)")

@PostMapping("/addBanners")

publicvoidputBanne