SpringBoot集成Swagger2自动生成API接口文档
一、导入依赖
<!-- Swagger的注解依赖包 -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>3.0.0</version>
</dependency>
<!-- Swagger接口文档页面包 -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>3.0.0</version>
</dependency>
二、配置类
package com.example.swagger2.config;
import io.swagger.annotations.ApiOperation;
import io.swagger.models.auth.In;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurationSupport;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.*;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spi.service.contexts.SecurityContext;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
import java.util.ArrayList;
import java.util.List;
/**
* @author feimao
* @date 2022-03-30
*/
@Configuration
@EnableSwagger2
public class Swagger2Config extends WebMvcConfigurationSupport {
/**
* 创建API
*/
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
// 是否启用Swagger（可写到配置文件application.yml中）
.enable(true)
// 用来创建该API的基本信息，展示在文档的页面中（自定义展示的信息）
.apiInfo(apiInfo())
// 设置哪些接口暴露给Swagger展示
.select()
// 扫描所有有注解的api，用这种方式更灵活
.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
// 扫描指定包中的swagger注解
// .apis(RequestHandlerSelectors.basePackage("com.example.swagger2"))
// 扫描所有 .apis(RequestHandlerSelectors.any())
//为任何接口生成API文档
.paths(PathSelectors.any())
.build()
/* 设置安全模式，swagger可以设置访问token */
//.securitySchemes(securitySchemes())
//.securityContexts(securityContexts())
// 统一请求前缀（可写到配置文件application.yml中）
.pathMapping("/dev-api");
}
/**
* 安全模式，这里指定token通过Authorization头请求头传递
*/
//private List<SecurityScheme> securitySchemes() {
// List<SecurityScheme> apiKeyList = new ArrayList<SecurityScheme>();
// apiKeyList.add(new ApiKey("Authorization", "Authorization", In.HEADER.toValue()));
// return apiKeyList;
//}
/**
* 安全上下文
*/
//private List<SecurityContext> securityContexts() {
// List<SecurityContext> securityContexts = new ArrayList<>();
// securityContexts.add(
// SecurityContext.builder()
// .securityReferences(defaultAuth())
// .operationSelector(o -> o.requestMappingPattern().matches("/.*"))
// .build());
// return securityContexts;
//}
/**
* 默认的安全上引用
*/
//private List<SecurityReference> defaultAuth() {
// AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything");
// AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];
// authorizationScopes[0] = authorizationScope;
// List<SecurityReference> securityReferences = new ArrayList<>();
// securityReferences.add(new SecurityReference("Authorization", authorizationScopes));
// return securityReferences;
//}
/**
* 配置swagger2的静态资源路径
*
* @param registry
*/
@Override
protected void addResourceHandlers(ResourceHandlerRegistry registry) {
// 解决静态资源无法访问
registry.addResourceHandler("/**")
.addResourceLocations("classpath:/static/");
// 解决swagger无法访问
registry.addResourceHandler("/swagger-ui.html")
.addResourceLocations("classpath:/META-INF/resources/");
// 解决swagger的js文件无法访问
registry.addResourceHandler("/webjars/**")
.addResourceLocations("classpath:/META-INF/resources/webjars/");
}
/**
* 添加摘要信息
*/
private ApiInfo apiInfo() {
// 用ApiInfoBuilder进行定制
return new ApiInfoBuilder()
// 设置标题
.title("标题：xx管理系统_接口文档")
// 描述
.description("描述：用于管理集团旗下公司的人员信息,具体包括XXX,XXX模块...")
// 作者信息
.contact(new Contact("feimao", "http://项目地址、公司官网.com", "123@163.com"))
// 版本
.version("版本号:1.0")
.build();
}
/**
* 创建一个分组（可选，创建分组后会在界面右上角切换）
* @return
*/
@Bean
public Docket docket() {
return new Docket(DocumentationType.SWAGGER_2)
.groupName("肥猫的分组")
// 配置分组详情
.apiInfo(apiInfo());
}
}
三、Swagger2注解详解
1、@Api ：请求类的说明
@Api：放在请求的类上，与 @Controller 并列，说明类的作用，如用户模块，订单类等。
tags="说明该类的作用"
value="该参数没什么意义，所以不需要配置"
举例：
@Api(tags = "账户相关模块")
@RestController
@RequestMapping("/api/account")
public class AccountController {
//TODO
}
3、@ApiImplicitParams、@ApiImplicitParam：方法参数的说明
@ApiImplicitParams：用在请求的方法上，包含一组参数说明
@ApiImplicitParam：对单个参数的说明
name：参数名
value：参数的汉字说明、解释
required：参数是否必须传
paramType：参数放在哪个地方
· header --> 请求参数的获取：@RequestHeader
· query --> 请求参数的获取：@RequestParam
· path（用于restful接口）--> 请求参数的获取：@PathVariable
· body（请求体）--> @RequestBody User user
· form（普通表单提交）
dataType：参数类型，默认String，其它值dataType="int"
defaultValue：参数的默认值
举例：
@ApiOperation(value="用户登录",notes="随边说点啥")
@ApiImplicitParams({
@ApiImplicitParam(name="mobile",value="手机号",required=true,paramType="form"),
@ApiImplicitParam(name="password",value="密码",required=true,paramType="form"),
@ApiImplicitParam(name="age",value="年龄",required=true,paramType="form",dataType="Integer")
})
@PostMapping("/login")
public AjaxResult login(@RequestParam String mobile, @RequestParam String password,
@RequestParam Integer age){
//TODO
return AjaxResult.OK();
}
单个参数举例
@ApiOperation("根据部门Id删除")
@ApiImplicitParam(name="depId",value="部门id",required=true,paramType="query")
@GetMapping("/delete")
public AjaxResult delete(String depId) {
//TODO
}
4、@ApiResponses、@ApiResponse：方法返回值的说明
@ApiResponses：方法返回对象的说明
@ApiResponse：每个参数的说明
code：数字，例如400
message：信息，例如"请求参数没填好"
response：抛出异常的类
举例：
@ApiOperation(value = "修改密码", notes = "方法的备注说明，如果有可以写在这里")
@ApiResponses({
@ApiResponse(code = 400, message = "请求参数没填好"),
@ApiResponse(code = 404, message = "请求路径找不到")
})
@PostMapping("/changepass")
public AjaxResult changePassword(@AutosetParam SessionInfo sessionInfo,
@RequestBody @Valid PasswordModel passwordModel) {
//TODO
}
5、@ApiModel：用于JavaBean上面，表示一个JavaBean
@ApiModel：用于JavaBean的类上面，表示此 JavaBean 整体的信息
（这种一般用在post创建的时候，使用 @RequestBody 这样的场景，请求参数无法使用 @ApiImplicitParam 注解进行描述的时候 ）
6. @ApiModelProperty：用在JavaBean的属性上面，说明属性的含义
@ApiModel和 @ApiModelProperty举例：
@ApiModel("修改密码所需参数封装类")
public class PasswordModel
{
@ApiModelProperty("账户Id")
private String accountId;
//TODO
}
总结：API文档浏览地址
配置好Swagger2并适当添加注解后，启动SpringBoot应用，
访问http://localhost:8080/swagger-ui.html 即可浏览API文档。
另外，我们需要为了API文档的可读性，适当的使用以上几种注解就可以。
四、把Swagger2的API接口导入ApiPost（postman同理）
1、访问http://ip:端口/swagger-ui.html 文档的首页，复制下面这个地址，浏览器打开后，直接Ctrl+S 保存json文件到电脑
2.打开ApiPost
