SpringBoot整合Swagger的方法示例

2024-07-14 08:42:38

字體：大中小

供稿：網(wǎng)友

依賴

<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 陳加兵 * */@Configurationpublic 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文檔的標題") //標題 .description("api文檔的描述") //描述 .contact( //添加開發(fā)者的一些信息  new Contact("愛撒謊的男孩", "https://chenjiabing666.github.io",  "18796327106@163.com")).version("1.0").build(); }}

啟動類

在springBoot的啟動類上添加一個注解即可配置成功： @EnableSwagger2

訪問api的路徑
http://ip/projectName/swagger-ui.html

注解說明

@Api

標注在類上，用來對這個類進行說明的
如果想要生成文檔，必須在類或者接口上標注
屬性如下：

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

@ApiOperation

用在API方法上，對該API做注釋，說明API的作用
不需要多講，看源碼，使用默認的value屬性即可，說明該方法的作用
屬性如下：

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

@ApiImplicitParams

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

@ApiImplicitParam

用在 @ApiImplicitParams 注解中，也可以單獨使用，說明一個請求參數(shù)的各個方面

詳細的屬性使用說明如下：

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

paramType屬性的詳細說明

query ：必須要和入?yún)⒌淖侄我粯樱部梢允褂?@RequestParam() 指定
path ：用于Restful的風格的url，請求的參數(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, "陳加兵"); }