添加依赖
<!-- swagger 3 -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-boot-starter</artifactId>
<version>3.0.0</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-oas</artifactId>
<version>3.0.0</version>
</dependency>
或者
<!-- API获取的包 -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>3.0.0</version>
</dependency>
<!-- 官方UI包 -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>3.0.0</version>
</dependency>
<!-- swagger 3 -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-boot-starter</artifactId>
<version>3.0.0</version>
</dependency>
配置并开启Swagger功能
创建swagger的配置类,配置swagger的基本信息,并在配置类头上加上当前类是配置类的注解和开启生成接口文档功能的注解
添加开关注解@EnableOpenApi
@EnableOpenApi //表示开启生成接口文档功能(只有开启了OpenApi,才可以实现生成接口文档的功能)
配置类
@Configuration //表明当前类是配置类
@EnableOpenApi //表示开启生成接口文档功能(只有开启了OpenApi,才可以实现生成接口文档的功能)
public class SwaggerConfig {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.OAS_30)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.swagger.demp"))
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("Swagger3接口文档")
.description("更多请咨询服务开发者")
.contact(new Contact("Ray", "http://www.baidu.com", "baidu@"))
.version("1.0")
.build();
}
}
配置类详解
RequestHandlerSelectors配置扫描路径的一些方法
// 扫描所有,项目中的所有接口都会被扫描到
any()
// 不扫描接口
none()
// 通过方法上的注解扫描,如withMethodAnnotation(GetMapping.class)只扫描get请求
withMethodAnnotation(final Class<? extends Annotation> annotation)
// 通过类上的注解扫描,如.withClassAnnotation(Controller.class)只扫描有controller注解的类中的接口
withClassAnnotation(final Class<? extends Annotation> annotation)
// 根据包路径扫描接口
basePackage(final String basePackage)
PathSelectors配置扫描请求的一些方法
any() // 任何请求都扫描
none() // 任何请求都不扫描
regex(final String pathRegex) // 通过正则表达式扫描
ant(final String antPattern) // 通过ant()指定请求扫描
开启关闭Swagger配置
@Bean
public Docket docket() {
return new Docket(DocumentationType.OAS_30)
// 设置是否启动Swagger,默认为true(不写即可),关闭后Swagger就不生效了
.enable(true)
}
Swagger开发环境配置
在开发中有开发环境、测试环境、发布环境,Swagger文档不应该在有些环境中出现,就比如发布环境,不仅占内存,而且接口信息还容易泄露出去;这里就简单演示一下如何在不同的环境下配置Swagger;
application.yml环境配置:
开发环境:
spring:
profiles:
active: dev
测试环境:
spring:
profiles:
active: test
配置开发环境dev和测试环境test显示Swagger文档:
@Bean
public Docket docket(Environment environment) {
Profiles profiles = Profiles.of("dev", "test"); // 设置要显示swagger的环境
boolean isOpen = environment.acceptsProfiles(profiles); // 判断当前是否处于该环境
return new Docket(DocumentationType.OAS_30)
// 设置是否启动Swagger,通过当前环境进行判断:isOpen
.enable(isOpen);
}
API分组
Swagger默认是一个default分组:
可以通过分组来实现对不同API的分类,分组可以使用Docket的groupName属性区分不同分组,并可以在Swagger中创建多个Docket的Bean实例来定义不同分组;
配置多个分组:
@Bean
public Docket docketCategory() {
return new Docket(DocumentationType.OAS_30)
.apiInfo(apiInfo())
// 分组名称
.groupName("Category")
.enable(true)
.select()
.apis(RequestHandlerSelectors.basePackage("com.yang.takeout.backend.controller"))
// 过滤请求,只扫描请求以/category开头的接口
.paths(PathSelectors.ant("/category/**"))
.build();
}
@Bean
public Docket docketEmployee() {
return new Docket(DocumentationType.OAS_30)
.apiInfo(apiInfo())
// 分组名称
.groupName("Employee")
.enable(true)
.select()
.apis(RequestHandlerSelectors.basePackage("com.yang.takeout.backend.controller"))
// 过滤请求,只扫描请求以/employee开头的接口
.paths(PathSelectors.ant("/employee/**"))
.build();
}
常用注解
swagger3的注解与swagger2相差很多,也兼容了swagger2的注解,区别如下:
@Api:用在请求的类上,表示对类的说明
tags="说明该类的作用,可以在UI界面上看到的注解"
value="该参数没什么意义,在UI界面上也看到,所以不需要配置"
@ApiOperation:用在请求的方法上,说明方法的用途、作用
value="说明方法的用途、作用"
notes="方法的备注说明"
@ApiImplicitParams:用在请求的方法上,表示一组参数说明
@ApiImplicitParam:用在@ApiImplicitParams注解中,指定一个请求参数的各个方面
name:参数名
value:参数的汉字说明、解释
required:参数是否必须传
paramType:参数放在哪个地方
· header --> 请求参数的获取:@RequestHeader
· query --> 请求参数的获取:@RequestParam
· path(用于restful接口)--> 请求参数的获取:@PathVariable
· div(不常用)
· form(不常用)
dataType:参数类型,默认String,其它值dataType="Integer"
defaultValue:参数的默认值
@ApiResponses:用在请求的方法上,表示一组响应
@ApiResponse:用在@ApiResponses中,一般用于表达一个错误的响应信息
code:数字,例如400
message:信息,例如"请求参数没填好"
response:抛出异常的类
@ApiModel:用于响应类上,表示一个返回响应数据的信息
(这种一般用在post创建的时候,使用@RequestBody这样的场景,
请求参数无法使用@ApiImplicitParam注解进行描述的时候)
@ApiModelProperty:用在属性上,描述响应类的属性
实例一 @ApiImplicitParams和@ApiImplicitParam 参数描述
post方式,根据name和age两个参数查询数据,返回信息;
我们用@ApiImplicitParams和@ApiImplicitParam,描述请求参数
/**
* 查询
* @param name
* @param age
* @return
*/
@PostMapping("/search")
@ApiImplicitParams({
@ApiImplicitParam(name = "name",value = "姓名",required = true,paramType = "query"),
@ApiImplicitParam(name = "age",value = "年龄",required = true,paramType = "query",dataType = "Integer")
})
@ApiOperation("测试查询")
public String search(String name,Integer age){
return name+":"+age;
}
@RestController
@Api(tags = "用户信息处理")
public class HelloController {
@GetMapping("/user")
@Operation(summary = "获取用户信息")
@ApiImplicitParams({@ApiImplicitParam(name = "username", value = "用户名"),
@ApiImplicitParam(name = "password", value = "密码")})
public UserEntity getUser(@RequestParam("username")String username,
@RequestParam("password")String password){
UserEntity user = new UserEntity();
user.setUsername(username);
user.setPassword(password);
return user;
}
}
标注在实体类上:
实例二 @ApiModel,@ApiModelProperty**实体参数描述
我们搞一个用户信息添加,使用@ApiModel,@ApiModelProperty注解来描述输入参数;
先搞一个用户信息实体User.java
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
/**
* 用户实体
* @author java1234_小锋
* @site www.java1234.com
* @company 南通小锋网络科技有限公司
* @create 2021-09-26 9:10
*/
@ApiModel("用户信息实体")
public class User {
@ApiModelProperty("编号")
private Integer id;
@ApiModelProperty("姓名")
private String name;
@ApiModelProperty("年龄")
private Integer age;
public User() {
}
public User(Integer id,String name, Integer age) {
this.id=id;
= name;
this.age = age;
}
public String getName() {
return name;
}
public void setName(String name) {
= name;
}
public Integer getAge() {
return age;
}
public void setAge(Integer age) {
this.age = age;
}
public Integer getId() {
return id;
}
public void setId(Integer id) {
this.id = id;
}
@Override
public String toString() {
return "User{" +
"id=" + id +
", name='" + name + '\'' +
", age=" + age +
'}';
}
}
参数上,直接用User user
/**
* 添加测试
* @param user
* @return
*/
@PostMapping("/add")
@ApiOperation("测试添加")
public String add(User user){
return user.getName()+":"+user.getAge();
实例三 @ApiResponses,@ApiResponse
我们搞一个根据id获取用户信息案例,通过@PathVariable获取id,返回User对象,以及通过@ApiResponses,@ApiResponse,描述响应码对应的描述信息
@GetMapping("/user/{id}")
@ApiOperation("根据ID获取用户信息")
@ApiImplicitParams({
@ApiImplicitParam(name = "id",value = "用户编号",required = true,paramType = "path")
})
@ApiResponses({
@ApiResponse(code=408,message="指定业务得报错信息,返回客户端"),
@ApiResponse(code=400,message="请求参数没填好"),
@ApiResponse(code=404,message="请求路径没有或页面跳转路径不对")
})
public User load(@PathVariable("id") Integer id){
return new User(id,"jack",32);
}
Swagger 3(OpenAPI 3)常用注解介绍
@OpenAPIDefinition
用于描述标签、文档信息、安全配置及外部文档,用在类上。
常用参数:
info
:描述文档信息,详情见以下的@Info
tags
:定义标签列表,详情见以下的@Tag
servers
:目标服务器连接列表,详情见以下的@Server
externalDocs
:API 的一些外部文档,详情见以下的@ExternalDocumentation
示例:
@OpenAPIDefinition(
tags = {
@Tag(name = "用户管理", description = "用户模块操作"),
@Tag(name = "角色管理", description = "角色模块操作")
},
info = @Info(
title = "用户接口 API 文档",
description = "用户数据管理......",
version = "1.0.0",
contact = @Contact(
name = "lanweihong",
email = "986310747@",
url = "https://www.lanweihong.com"
),
license = @License(
name = "Apache 2.0",
url = "http://www.apache.org/licenses/LICENSE-2.0.html"
)
),
servers = {
@Server(description = "生产环境服务器", url = "https://xxxx.com/api/v1"),
@Server(description = "测试环境服务器", url = "https://test.xxxx.com/api/v1")
},
security = @SecurityRequirement(name = "Oauth2"),
externalDocs = @ExternalDocumentation(
description = "项目编译部署说明",
url = "http://localhost/deploy/README.md"
)
)
@Configuration
public class SwaggerConfig {
// ···
}
@Info
用于说明文档信息,用在 @OpenAPIDefinition
中。
常用参数:
title
:应用标题description
:应用描述contact
:联系信息,详情看@Contact
license
:许可信息,详情看@License
version
:版本
示例:
@OpenAPIDefinition(
info = @Info(
title = "用户接口 API 文档",
description = "用户数据管理......",
version = "1.0.0",
contact = @Contact(name = "lanweihong", email = "986310747@", url = "https://www.lanweihong.com"),
license = @License(name = "Apache 2.0", url = "http://www.apache.org/licenses/LICENSE-2.0.html")
)
)
@Configuration
public class SwaggerConfig {
// ···
}
@Tag
对一个 operation 进行说明或定义的标签,用在类或方法上,也可以用在 @OpenAPIDefinition
中定义标签。
常用参数:
name
:名称description
:描述
示例:
用在类上:
@Tag(name = "用户管理")
@RestController
public class UserController {
// ···
}
用在 @OpenAPIDefinition
中定义标签:
@OpenAPIDefinition(
tags = {
@Tag(name = "用户管理", description = "用户模块操作"),
@Tag(name = "角色管理", description = "角色模块操作")
}
)
@Configuration
public class SwaggerConfig {
// ···
}
值得注意的是,
@Tag
在使用 Springfox 整合时,配置在 Controller 上使用并没有生效,在 Swagger UI 中没有看到相关显示。 解决方法是使用 2.X 版本的注解替代:@Api(tags = "用户管理")
。
这个问题在 Springdoc 中不存在,通过 Springdoc 来生成 API 文档时,@Tag
使用正常,在 Swagger UI 中正常显示
@Contact
用于描述联系人信息,用在 @Info
中。
常用参数:
name
:唯一名称(个人/组织)url
:指向联系人信息的 URL
示例:
@OpenAPIDefinition(
info = @Info(
contact = @Contact(
name = "Li.chen",
email = "mail",
url = "www"
)
)
)
@Configuration
public class SwaggerConfig {
// ···
}
复制代码
@License
用于藐视许可证信息,用在 @Info
中。
常用参数:
name
:许可证名称url
:指向许可证的 URL
示例:
@OpenAPIDefinition(
servers = {
@Server(description = "生产环境服务器", url = "https://xxxx.com/api/v1"),
@Server(description = "测试环境服务器", url = "https://test.xxxx.com/api/v1")
}
)
@Configuration
public class SwaggerConfig {
// ···
}
复制代码
Server
用于配置目标主机,用在 @OpenAPIDefinition
中。
常用参数:
url
:主机地址description
:主机描述
示例:
@OpenAPIDefinition(
servers = {
@Server(description = "生产环境服务器", url = "https://xxxx.com/api/v1"),
@Server(description = "测试环境服务器", url = "https://test.xxxx.com/api/v1")
}
)
@Configuration
public class SwaggerConfig {
// ···
}
复制代码
@Operation
用于说明方法用途,用在方法上。
参数:
summary
:方法概要,方法的一个简单介绍,建议 120 个字符内description
:方法描述,一般是很长的内容hidden
:是否隐藏
示例:
@Operation(summary = "查询用户列表", description = "返回所有用户数据")
@GetMapping("/users")
public String getUseList() {
return "";
}
@Parameter
用于说明方法参数,用在方法参数上。
参数:
name
:指定的参数名in
:参数位置,可选query
、header
、path
或cookie
,默认为空,表示忽略description
:参数描述required
:是否必填,默认为false
示例:
@Operation(summary = "删除用户")
@DeleteMapping("/users/{username}")
public JsonResult<UserVO> deleteUserByName(
@Parameter(name = "username", in = ParameterIn.PATH, description = "用户名", required = true)
@PathVariable("username") String userName
) {
// TODO
return JsonResult.ok();
}
@ApiResponse
用于说明一个响应信息,用在 @ApiResponses
中。
参数:
responseCode
:HTTP 响应码description
:描述
示例:
@Operation(summary = "通过用户名查询用户", description = "根据用户名查询用户详细信息")
@ApiResponses(value = {
@ApiResponse(responseCode = "200", description = "请求成功"),
@ApiResponse(responseCode = "404", description = "用户不存在", content = @Content)
})
@GetMapping("/{username}")
public JsonResult<UserVO> getUserByName(@Parameter(description = "用户名", required = true) @PathVariable("username") String userName) {
// TODO
return JsonResult.ok();
}
@ApiResponses
用于说明一组响应信息,比如一个请求可能返回多种响应情况,比如成功信息(200),也有可能抛参数异常(400),用在方法上。
参数:
value
:@ApiResponse
数组
示例参考以上的 @ApiResponse
。
@Schema
用于描述数据对象信息或数据对象属性,比如各种 POJO 类及属性,用在类或类属性上。
参数:
name
:属性名称description
:属性描述required
:是否必须minLength
:字符最小长度maxLength
:字符最大长度
示例:
@Schema(description = "用户实体")
public class UserVO {
@Schema(description = "用户名")
private String userName;
@Schema(description = "邮箱")
private String email;
// Getter And Setter ...
}
值得注意的是,当使用 Springfox 整合时, @Schema
配置在类上时在 Swagger UI 中并未生成其配置的信息,但是配置在类属性上却是正常的。配置在类上时可使用 @ApiModel(description = "用户参数对象")
来替代。
这个问题在使用 Springdoc 整合时不存在,在 Springdox 整合使用时,@Schema
配置在类和属性上均正常。
@Hidden
用于隐藏资源、类或属性,用在类、方法或属性上。
示例:
@RestController
@RequestMapping("/api/roles")
// 隐藏整个 RoleController
@Hidden
public class RoleController {
@GetMapping("")
public JsonResult<String> queryRoleList() {
return JsonResult.ok();
}
}
一般常用的也就这几个注解,若想要了解更多的注解,请参阅 OpenAPI Specification 。
整合 Swagger 3(OpenAPI 3)
添加依赖
编辑 pom.xml
,添加依赖:
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-boot-starter</artifactId>
<version>3.0.0</version>
</dependency>
添加 Swagger 配置类
- 添加 Swagger 属性配置类,用于封装 Swagger 配置参数:
@ConfigurationProperties(prefix = "spring.swagger")
@Data
public class SwaggerProperties {
private Boolean enable;
private String groupName;
private String basePackage;
private String version;
private String title;
private String description;
private String contactName;
private String contactEmail;
private String contactUrl;
}
- 添加 Swagger 配置类,添加注解
@EnableOpenApi
:
@Configuration
@EnableOpenApi
@EnableConfigurationProperties(value = {SwaggerProperties.class})
public class SwaggerConfig {
SwaggerProperties swaggerProperties;
@Autowired
public void setSwaggerProperties(SwaggerProperties swaggerProperties) {
this.swaggerProperties = swaggerProperties;
}
/**
* API
* @return
*/
@Bean
public Docket adminApi() {
// OAS_30:区别于 V2,(OpenAPI Specification 的简称 OAS)
return new Docket(
// 使用 OpenAPI 3.0
DocumentationType.OAS_30)
.enable(swaggerProperties.getEnable())
// API 信息
.apiInfo(getAdminApiInfo())
// API 分组
.groupName(swaggerProperties.getGroupName())
.select()
// 对某个包的接口进行监听
.apis(RequestHandlerSelectors.basePackage(swaggerProperties.getBasePackage()))
// 监听所有接口
// .apis(RequestHandlerSelectors.any())
.paths(PathSelectors.any())
.build();
}
/**
* API 信息
* @return
*/
private ApiInfo getAdminApiInfo() {
return new ApiInfoBuilder()
// 文档标题
.title(swaggerProperties.getTitle())
// 文档描述
.description(swaggerProperties.getDescription())
// 联系人信息
.contact(new Contact(swaggerProperties.getContactName(), swaggerProperties.getContactUrl(), swaggerProperties.getContactEmail()))
// 文档版本
.version(swaggerProperties.getVersion())
.build();
}
}
使用 Swagger 3
- 添加 Controller:
@RestController
@RequestMapping("/api/users")
// @Tag 注解不生效,似乎是 BUG,相关 issues:https:///springfox/springfox/issues/3668,因此这里使用 2.X 的注解 @Api
// @Tag(name = "用户管理", description = "用户数据增删改查")
@Api(tags = "用户管理")
public class UserController {
@Operation(summary = "查询用户列表", description = "返回所有用户数据")
@GetMapping("")
public JsonResult<List<UserVO>> getUserList(@Parameter(description = "用户名") @RequestParam(value = "username", required = false) String userName) {
List<UserVO> result = new ArrayList<>();
result.add(new UserVO("zhangsan", "zhangsan@lanweihong.com"));
result.add(new UserVO("lisi", "lisi@lanweihong.com"));
return JsonResult.ok(result);
}
@Operation(summary = "通过用户名查询用户", description = "根据用户名查询用户详细信息")
@ApiResponses(value = {
@ApiResponse(responseCode = "200", description = "请求成功"),
@ApiResponse(responseCode = "404", description = "用户不存在", content = @Content)
})
@GetMapping("/{username}")
public JsonResult<UserVO> getUserByName(@Parameter(description = "用户名", required = true) @PathVariable("username") String userName) {
// TODO
return JsonResult.ok();
}
@Operation(summary = "新增用户")
@PostMapping("")
public JsonResult<UserVO> addUser(@Parameter(required = true) @Valid @RequestBody UserParam param) {
// TODO
return JsonResult.ok();
}
@Operation(summary = "修改用户")
@PutMapping("")
public JsonResult<UserVO> updateUser(@Parameter(description = "用户参数", required = true) @Valid @RequestBody UserParam param) {
// TODO
return JsonResult.ok();
}
@Operation(summary = "删除用户")
@DeleteMapping("/{username}")
public JsonResult<UserVO> deleteUserByName(@Parameter(name = "username", in = ParameterIn.PATH, description = "用户名", required = true) @PathVariable("username") String userName) {
// TODO
return JsonResult.ok();
}
@Hidden
@PostMapping("/test")
public JsonResult<UserVO> testAddUser(@Valid @RequestBody UserParam userParam) {
// TODO
return JsonResult.ok();
}
}
- 添加 VO:
@Getter
@Setter
// @Schema 注解用在类上不生效,使用 @ApiModel 替代
@ApiModel(description = "用户实体")
@ToString
public class UserVO {
public UserVO() {
}
public UserVO(String userName, String email) {
this.userName = userName;
this.email = email;
}
@Schema(name = "用户名", description = "用户名")
private String userName;
@Schema(description = "邮箱")
private String email;
}
- 编辑项目
application.yml
,添加以下参数:
# 自定义 Swagger 配置
spring:
swagger:
enable: true
groupName: 前端
basePackage: com.lanweihong.springfox.swagger
version: 1.0.0
title: 前端
description: 开发文档
contactName: lanweihong
contactEmail: 986310747@
contactUrl: blog.lanweihong.com
- 项目中如果使用了 Spring Security 的,要添加以下配置放行 Swagger UI 的相关资源:
@Configuration
public class WebSecurityConfig extends WebSecurityConfigurerAdapter {
@Override
public void configure(WebSecurity web) throws Exception {
web.ignoring().antMatchers("/v3/api-docs",
"/v3/api-docs/**",
"/swagger-resources/**",
"/swagger-ui/**");
}
}
SpringMvc放行
package org.fh.config;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.ViewControllerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
/**
* 说明:Swagger 拦截配置
* 作者:FH Admin
* from fhadmin.org
*/
@Configuration
public class WebMvcConfig implements WebMvcConfigurer {
@Override
public void addResourceHandlers(ResourceHandlerRegistry registry) {
registry.
addResourceHandler("/swagger-ui/**")
.addResourceLocations("classpath:/META-INF/resources/webjars/springfox-swagger-ui/")
.resourceChain(false);
}
@Override
public void addViewControllers(ViewControllerRegistry registry) {
registry.addViewController("/swagger-ui/")
.setViewName("forward:/swagger-ui/index.html");
}
}
打开地址:http://localhost:8080/swagger-ui/index.html
使用第三方ui
添加如下依赖
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>swagger-bootstrap-ui</artifactId>
<version>1.9.6</version>
</dependency>
输入访问地址 /doc.html
2、bootstrap-ui 访问 http://localhost:8080/doc.html
<!-- 引入swagger-bootstrap-ui包 /doc.html-->
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>swagger-bootstrap-ui</artifactId>
<version>1.9.1</version>
</dependency>
3、mg-ui 访问 http://localhost:8080/document.html
<!-- 引入swagger-ui-layer包 /document.html-->
<dependency>
<groupId>com.zyplayer</groupId>
<artifactId>swagger-mg-ui</artifactId>
<version>1.0.6</version>
</dependency>