SpringBoot项目集成swagger2
什么是swagger2
编写和维护接口文档是每个程序员的职责,根据 Swagger2 可以快速帮助我们编写最新的API接口文档,再也不用担心开会前仍忙于整理各种资料了,间接提升了团队开发的沟通效率。常用注解swagger通过注解表明该接口会生成文档,包括接口名、请求方法、参数、返回信息的等等。
swagger2常用的注解说明
注解 | 属性 | 值 | 备注 |
---|---|---|---|
@Api | value | 字符串 | 可用在class头上,class描述 |
description | 字符串 | ||
@Api(value = “xxx”, description = “xxx”) | |||
@ApiModel | value | 字符串 | 可用在实体类上,不可重复 |
description | 字符串 | 可用在实体类上,实体类描述 | |
@ApiModelProperty | value | 字符串 | 可用在实体类属性上,属性说明 |
@ApiOperation | value | 字符串 | 可用在方法头上.参数的描述容器 |
notes | 字符串 | ||
@ApiOperation(value = “xxx”, notes = “xxx”) | |||
@ApiImplicitParam | name | 字符串 与参数命名对应 | 可用在@ApiImplicitParams里 |
value | 字符串 | 参数中文描述 | |
required | 布尔值 | true/false | |
dataType | 字符串 | 参数类型 | |
paramType | 字符串 | 参数请求方式:query/path | |
query:对应@RequestParam?传递 | |||
path: 对应@PathVariable{}path传递 | |||
defaultValue | 字符串 | 在api测试中默认值 | |
用例参见项目中的设置 | |||
@ApiResponses | {} | @ApiResponse数组 | 可用在方法头上.参数的描述容器 |
@ApiResponses({@ApiResponse1,@ApiResponse2,…}) | |||
@ApiResponse | code | 整形 | 可用在@ApiResponses里 |
message | 字符串 | 错误描述 | |
@ApiResponse(code = 200, message = “Successful”) |
快速入门
引入依赖
<!-- swagger2 -->
<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>
SwaggerConfig 配置
package io.yjff.demo.config;
import com.google.common.base.Predicates;
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.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
/**
* description: Swagger2 配置类
* @Configuration 让 Spring 容器加载该配置类
* date: 2020/6/14 14:22
* author: ***
* version: 1.0
*/
@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket api() {
return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).pathMapping("/").
select() // 选择那些路径和api会生成document
.apis(RequestHandlerSelectors.any())// 对所有api进行监控
// 不显示错误的接口地址
.paths(Predicates.not(PathSelectors.regex("/error.*")))// 错误路径不监控
.paths(PathSelectors.regex("/.*"))// 对根下所有路径进行监控
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder().title("产品接口文档")
// .contact(new Contact("***", "", "******@qq.com"))
.description("demo生成的接口文档")
// .termsOfServiceUrl("NO terms of service")
// .license("The Apache License, Version 2.0")
// .licenseUrl("http://www.apache.org/licenses/LICENSE-2.0.html")
// .version("v1.0")
.build();
}
}
controller注解
@Api
@Slf4j
@RestController
@RequestMapping("user")
@Api(tags = "用户管理")
public class UserController {
}
@ApiOperation
@ApiOperation(value = "用户列表", notes = "用户列表查询")
@GetMapping("list")
public List<UserEntity> list() {
return Collections.emptyList();
}
@ApiParam
@ApiOperation(value = "用户列表1", notes = "用户列表查询")
@GetMapping("list1")
public List<UserEntity> list1(@ApiParam(name = "userName", value = "用户名", required = true) @RequestParam("userName") String userName,
@ApiParam(name = "age", value = "年龄") @RequestParam(value = "age", required = false) Integer age) {
log.info("username:{};age:{}", userName, age);
return Collections.emptyList();
}
@ApiImplicitParams & @ApiImplicitParam
@ApiOperation(value = "用户列表2", notes = "用户列表查询")
@GetMapping("list2")
@ApiImplicitParams({
@ApiImplicitParam(name = "userName", value = "用户名", required = true, paramType = "query", dataType = "string"),
@ApiImplicitParam(name = "age", value = "年龄", paramType = "query", dataType = "Integer")
})
public List<UserEntity> list2(@RequestParam("userName") String userName,
@RequestParam(value = "age", required = false) Integer age) {
return Collections.emptyList();
}
@ApiIgnore
使用该注解忽略这个API,用于类或者方法上
@ApiOperation(value = "用户列表3", notes = "用户列表查询")
@GetMapping("list3")
@ApiImplicitParams({
@ApiImplicitParam(name = "userName", value = "用户名", required = true, paramType = "query", dataType = "string"),
@ApiImplicitParam(name = "age", value = "年龄", paramType = "query", dataType = "Integer")
})
public List<UserEntity> list3(@ApiIgnore @RequestParam Map<String, Object> param) {
log.info("params:{}", param);
return Collections.emptyList();
}
@ApiResponses & @ApiResponse
@ApiOperation(value = "用户列表2", notes = "用户列表查询")
@GetMapping("list2")
@ApiImplicitParams({
@ApiImplicitParam(name = "userName", value = "用户名", required = true, paramType = "query", dataType = "string"),
@ApiImplicitParam(name = "age", value = "年龄", paramType = "query", dataType = "Integer")
})
@ApiResponses(value = {
@ApiResponse(code = 200, message = "Success"),
@ApiResponse(code = 400, message = "参数问题"),
@ApiResponse(code = 401, message = "未登录"),
@ApiResponse(code = 404, message = "找不到路径"),
@ApiResponse(code = 500, message = "服务器内部异常")}
)
public List<UserEntity> list2(@RequestParam("userName") String userName,
@RequestParam(value = "age", required = false) Integer age) {
return Collections.emptyList();
}
实体注解
@ApiModel & @ApiModelProperty
package io.yjff.demo.entity;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;
/**
* @description: user实体
* @author: ***
* @time: 2020/6/9 17:01
*/
@Data
@ApiModel(value = "UserEntity", description = "用户实体")
public class UserEntity {
@ApiModelProperty("ID")
private Long id;
@ApiModelProperty("用户名")
private String userName;
@ApiModelProperty("年龄")
private Integer age;
}
接口测试
启动swagger项目,访问项目ip+/端口+/工程路径+/swagger-ui.html访问swagger接口文档页面。打开对应的方法,输入接口参数点击按钮try it out即可调用对应的接口。