快捷導(dǎo)航

SpringBoot整合Swagger的方法示例

更新時(shí)間：2018年10月22日 13:56:07 作者：Chenjiabing

這篇文章主要介紹了SpringBoot整合Swagger的方法示例，詳細(xì)介紹了SpringBoot如何整合Swagger以及swagger注解，具有一定的參考價(jià)值，感興趣的小伙伴們可以參考一下

依賴

<dependency>
 <groupId>io.springfox</groupId>
 <artifactId>springfox-swagger2</artifactId>
 <version>2.7.0</version>
</dependency>
<dependency>
 <groupId>io.springfox</groupId>
 <artifactId>springfox-swagger-ui</artifactId>
 <version>2.7.0</version>
</dependency>

配置類

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;

/**
 * Swagger的配置類
 * @author 陳加兵
 *
 */
@Configuration
public class SwaggerConfig{
 /**
 * 創(chuàng)建用戶API文檔
 * @return
 */
 @Bean
 public Docket createRestUserApi(){
 return new Docket(DocumentationType.SWAGGER_2)
 .groupName("user") 
 .apiInfo(apiInfo()) //api的信息
 .select()
 .apis(RequestHandlerSelectors
  .basePackage("cn.tedu.mycat.controller")) //添加包掃描
 .paths(PathSelectors.any()).build();

 }

 /**
 * 創(chuàng)建API信息
 */
 private ApiInfo apiInfo(){
 return new ApiInfoBuilder()
 .title("api文檔的標(biāo)題") //標(biāo)題
 .description("api文檔的描述") //描述
 .contact( //添加開(kāi)發(fā)者的一些信息
  new Contact("愛(ài)撒謊的男孩", "https://chenjiabing666.github.io",
  "18796327106@163.com")).version("1.0").build();
 }

}

啟動(dòng)類

在springBoot的啟動(dòng)類上添加一個(gè)注解即可配置成功： @EnableSwagger2

訪問(wèn)api的路徑
http://ip/projectName/swagger-ui.html

注解說(shuō)明

@Api

標(biāo)注在類上，用來(lái)對(duì)這個(gè)類進(jìn)行說(shuō)明的
如果想要生成文檔，必須在類或者接口上標(biāo)注
屬性如下：

屬性名稱	備注	默認(rèn)值
value	url的路徑值
tags	如果設(shè)置這個(gè)值、value的值會(huì)被覆蓋
description	對(duì)api資源的描述
basePath	基本路徑可以不配置
position	如果配置多個(gè)Api 想改變顯示的順序位置
produces	For example, “application/json, application/xml”
consumes	For example, “application/json, application/xml”
protocols	Possible values: http, https, ws, wss.
authorizations	高級(jí)特性認(rèn)證時(shí)配置
hidden	配置為true 將在文檔中隱藏

@ApiOperation

用在API方法上，對(duì)該API做注釋，說(shuō)明API的作用
不需要多講，看源碼，使用默認(rèn)的value屬性即可，說(shuō)明該方法的作用
屬性如下：

value	url的路徑值
tags	如果設(shè)置這個(gè)值、value的值會(huì)被覆蓋
notes	對(duì)api資源的描述
response	返回的對(duì)象，在文檔中點(diǎn)擊Model可以獲取該配置的內(nèi)容
responseContainer	這些對(duì)象是有效的 “List”, “Set” or “Map”.，其他無(wú)效
responseReference	可以不配置
httpMethod	可以接受 “GET”, “HEAD”, “POST”, “PUT”, “DELETE”, “OPTIONS” and “PATCH”
position	如果配置多個(gè)Api 想改變顯示的順序位置
produces	同 Api中的定義
consumes	同 Api中的定義
protocols	同 Api中的定義
authorizations	同 Api中的定義
hidden	是否隱藏，true 或者false ，這個(gè)可以隱藏后臺(tái)接口
code	http的狀態(tài)碼默認(rèn) 200
extensions	擴(kuò)展屬性

@ApiImplicitParams

用來(lái)包含API的一組參數(shù)注解，可以簡(jiǎn)單的理解為參數(shù)注解的集合聲明
很重要，這個(gè)注解其中包含接口入?yún)⒌脑敿?xì)說(shuō)明
內(nèi)容是集合

@ApiImplicitParam

用在 @ApiImplicitParams 注解中，也可以單獨(dú)使用，說(shuō)明一個(gè)請(qǐng)求參數(shù)的各個(gè)方面

詳細(xì)的屬性使用說(shuō)明如下：

name ：屬性的字段名稱，相當(dāng)于form表單中的name，這個(gè)就是入?yún)⒌淖侄?/li>
dataType ：參數(shù)的類型，標(biāo)識(shí)，字符串
value ：該參數(shù)的描述
required ：是否必填，布爾值
defaultValue ：缺省值，會(huì)在文檔中缺省填入，這樣更方面造數(shù)據(jù)，不需要調(diào)用接口的去填值了
paramType ：指定參數(shù)的入?yún)?shù)方式（也就是請(qǐng)求參數(shù)的位置），其中有四種常用的，如下：
- query
- path
- body
- form

paramType屬性的詳細(xì)說(shuō)明

query ：必須要和入?yún)⒌淖侄我粯?，也可以使?@RequestParam() 指定
path ：用于Restful的風(fēng)格的url，請(qǐng)求的參數(shù)寫在路徑上，如下：

@ApiOperation(value="根據(jù)用戶Id獲取用戶信息",response=User.class,hidden=false)
 @ApiImplicitParams({
 @ApiImplicitParam(paramType = "path", name = "id", dataType="Integer", required = false, value = "用戶的id", defaultValue = "1")
 })
 @GetMapping("/user/get/{id}")
 public Object getUser(@PathVariable("id")Integer id){
 return new User(id, "陳加兵");
 }