swagger介绍
文档组件，前后端开发人员可以查看接口文档，为前后端开发人员的开发统一接口，方便后续的前后端联调对接工作。
Springfox对应的maven坐标如下：
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
swagger常用注解
| 注解 | 说明 |
|---|---|
| @Api | 用在请求的类上，例如Controller，表示对类的说明 |
| @ApiModel | 用在类上，通常是实体类，表示一个返回响应数据的信息 |
| @ApiModelProperty | 用在属性上，描述响应类的属性 |
| @ApiOperation | 用在请求的方法上，说明方法的用途、作用 |
| @ApiImplicitParams | 用在请求的方法上，表示一组参数说明 |
| @ApiImplicitParam | 用在@ApiImplicitParams注解中，指定一个请求参数的各个方面 |
swagger入门案例
1，创建maven工程swagger_demo并配置pom.xml文件
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<parent>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-parent</artifactId>
<version>2.2.2.RELEASE</version>
<relativePath/>
</parent>
<groupId>cn.test</groupId>
<artifactId>swagger_demo</artifactId>
<version>0.0.1-SNAPSHOT</version>
<name>swagger_demo</name>
<description>Demo project for Spring Boot</description>
<properties>
<java.version>1.8</java.version>
</properties>
<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
<dependency>
<groupId>org.projectlombok</groupId>
<artifactId>lombok</artifactId>
</dependency>
<!--swagger依赖-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
</dependencies>
</project>
2，创建application-dev.yaml文件
server:
port: 9000
创建application.yaml文件
spring:
profiles:
active: dev
3，创建实体类User和Menu
@Data
//@ApiModel实体类
@ApiModel(description = "用户实体")
public class User {
//@ApiModelProperty属性
@ApiModelProperty(value = "主键")
private int id;
@ApiModelProperty(value = "姓名")
private String name;
@ApiModelProperty(value = "年龄")
private int age;
@ApiModelProperty(value = "地址")
private String address;
}
@Data
//实体类
@ApiModel(description = "菜单实体")
public class Menu {
//属性
@ApiModelProperty(value = "主键")
private int id;
@ApiModelProperty(value = "菜单名称")
private String name;
}
4，创建UserController和MenuController
@RestController
@RequestMapping("/user")
//@Api用于Controller上
@Api(tags = "用户控制器")
public class UserController {
@GetMapping("/getUsers")
//@ApiOperation用于controller中方法上
@ApiOperation(value = "查询所有用户", notes = "查询所有用户信息")
public List<User> getAllUsers(){
User user = new User();
user.setName("张三");
List<User> list = new ArrayList<>();
list.add(user);
return list;
}
@PostMapping("/save")
//@ApiOperation用于controller中方法上
@ApiOperation(value = "新增用户", notes = "新增用户信息")
public String save(@RequestBody User user){
return "OK";
}
@PutMapping("/update")
//@ApiOperation用于controller中方法上
@ApiOperation(value = "修改用户", notes = "修改用户信息")
public String update(@RequestBody User user){
return "OK";
}
@DeleteMapping("/delete")
//@ApiOperation用于controller中方法上
@ApiOperation(value = "删除用户", notes = "删除用户信息")
public String delete(int id){
return "OK";
}
//@ApiImplicitParams对参数进行说明
@ApiImplicitParams({
@ApiImplicitParam(name = "pageNum", value = "页码",
required = true, type = "Integer"),
@ApiImplicitParam(name = "pageSize", value = "每页条数",
required = true, type = "Integer"),
})
//@ApiOperation用于controller中方法上
@ApiOperation(value = "分页查询用户信息")
@GetMapping(value = "page/{pageNum}/{pageSize}")
public String findByPage(@PathVariable Integer pageNum,
@PathVariable Integer pageSize) {
return "OK";
}
}
@RestController
@RequestMapping("/menu")
@Api(tags = "菜单控制器")
public class MenuController {
@GetMapping("/getMenus")
@ApiOperation(value = "查询所有菜单", notes = "查询所有菜单信息")
public List<Menu> getMenus(){
Menu menu = new Menu();
menu.setId(100);
menu.setName("itcast");
List<Menu> list = new ArrayList<>();
list.add(menu);
return list;
}
@PostMapping("/save")
@ApiOperation(value = "新增菜单", notes = "新增菜单信息")
public String save(@RequestBody Menu menu){
return "OK";
}
@PutMapping("/update")
@ApiOperation(value = "修改菜单", notes = "修改菜单信息")
public String update(@RequestBody Menu menu){
return "OK";
}
@DeleteMapping("/delete")
@ApiOperation(value = "删除菜单", notes = "删除菜单信息")
public String delete(int id){
return "OK";
}
@ApiImplicitParams({
@ApiImplicitParam(name = "pageNum", value = "页码",
required = true, type = "Integer"),
@ApiImplicitParam(name = "pageSize", value = "每页条数",
required = true, type = "Integer"),
})
@ApiOperation(value = "分页查询菜单信息")
@GetMapping(value = "page/{pageNum}/{pageSize}")
public String findByPage(@PathVariable Integer pageNum,
@PathVariable Integer pageSize) {
return "OK";
}
}
5，创建配置类SwaggerAutoConfiguration
@Configuration
@EnableSwagger2
public class SwaggerAutoConfiguration {
@Bean
public Docket createRestApi1() {
Docket docket = new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo()).groupName("用户接口组")
.select()
//为当前包路径
.apis(RequestHandlerSelectors.basePackage("cn.ben.controller.user"))
.build();
return docket;
}
@Bean
public Docket createRestApi2() {
Docket docket = new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo()).groupName("菜单接口组")
.select()
//为当前包路径
.apis(RequestHandlerSelectors.basePackage("cn.ben.controller.menu"))
.build();
return docket;
}
//构建 api文档的详细信息
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
//页面标题
.title("API接口文档")
//创建人
.contact(new Contact("程序员", "http://www.ben.com", ""))
//版本号
.version("1.0")
//描述
.description("API 描述")
.build();
}
}
6，创建启动类SwaggerDemoApplication
@SpringBootApplication
public class SwaggerDemoApplication {
public static void main(String[] args) {
SpringApplication.run(SwaggerDemoApplication.class, args);
}
}
7，执行启动类main方法启动项目，访问地址：http://localhost:9000/swagger-ui.html
可以在用户控制器中发送模拟请求，通过f12可以看到具体发送的
knife4j
knife4j是为Java MVC框架集成Swagger生成Api文档的增强解决方案,前身是swagger-bootstrap-ui,取名knife4j是希望它能像一把匕首一样小巧,轻量,并且功能强悍!其底层是对Springfox的封装，使用方式也和Springfox一致，只是对接口文档UI进行了优化。
核心功能：
文档说明：根据Swagger的规范说明，详细列出接口文档的说明，包括接口地址、类型、请求示例、请求参数、响应示例、响应参数、响应码等信息，对该接口的使用情况一目了然。
在线调试：提供在线接口联调的强大功能，自动解析当前接口参数,同时包含表单验证，调用参数可返回接口响应内容、headers、响应时间、响应状态码等信息，帮助开发者在线调试。
knife4j入门案例
1，创建maven工程knife4j_demo并配置pom.xml文件
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<parent>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-parent</artifactId>
<version>2.2.2.RELEASE</version>
<relativePath/>
</parent>
<groupId>com.ben</groupId>
<artifactId>knife4j_demo</artifactId>
<version>1.0-SNAPSHOT</version>
<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-spring-boot-starter</artifactId>
<version>2.0.1</version>
</dependency>
<dependency>
<groupId>org.projectlombok</groupId>
<artifactId>lombok</artifactId>
</dependency>
</dependencies>
</project>
2，创建实体类User和Menu
参考swagger入门案例步骤3
3，创建UserController和MenuController
参考swagger入门案例步骤4
4，创建配置属性类SwaggerProperties
/*
*配置属性类，用于封装接口文档相关属性，从配置文件读取信息封装成当前对象
*/
@Data
@ConfigurationProperties(prefix = "pinda.swagger")
public class SwaggerProperties {
private String title = "在线文档"; //标题
private String group = ""; //自定义组名
private String description = "在线文档"; //描述
private String version = "1.0"; //版本
private Contact contact = new Contact(); //联系人
private String basePackage = "com.ben.pinda"; //swagger会解析的包路径
private List<String> basePath = new ArrayList<>(); //swagger会解析的url规则
private List<String> excludePath = new ArrayList<>();//在basePath基础上需要排除的url规则
private Map<String, DocketInfo> docket = new LinkedHashMap<>(); //分组文档
public String getGroup() {
if (group == null || "".equals(group)) {
return title;
}
return group;
}
@Data
public static class DocketInfo {
private String title = "在线文档"; //标题
private String group = ""; //自定义组名
private String description = "在线文档"; //描述
private String version = "1.0"; //版本
private Contact contact = new Contact(); //联系人
private String basePackage = ""; //swagger会解析的包路径
private List<String> basePath = new ArrayList<>(); //swagger会解析的url规则
private List<String> excludePath = new ArrayList<>();//在basePath基础上需要排除的url
public String getGroup() {
if (group == null || "".equals(group)) {
return title;
}
return group;
}
}
@Data
public static class Contact {
private String name = "pinda"; //联系人
private String url = ""; //联系人url
private String email = ""; //联系人email
}
}
5，创建application.yml文件
server:
port: 7788
pinda:
swagger:
enabled: true #是否启用swagger
docket:
user: #Map<String, DocketInfo> docket的key
title: 用户模块 #Map<String, DocketInfo> docket的value
base-package: cn.ben.controller.user #Map<String, DocketInfo> docket的value
menu:
title: 菜单模块
base-package: cn.ben.controller.menu
6，创建配置类SwaggerAutoConfiguration
@Configuration
@EnableSwagger2
@EnableConfigurationProperties(SwaggerProperties.class)
@ConditionalOnProperty(name = "pinda.swagger.enabled", havingValue = "true",
matchIfMissing = true)
public class SwaggerAutoConfiguration implements BeanFactoryAware {
//beanFactory用于注册单例对象
private BeanFactory beanFactory;
@Override
public void setBeanFactory(BeanFactory beanFactory) throws BeansException {
this.beanFactory = beanFactory;
}
@Autowired
SwaggerProperties swaggerProperties;
@Bean
@ConditionalOnMissingBean
public List<Docket> createRestApi(){
ConfigurableBeanFactory configurableBeanFactory =
(ConfigurableBeanFactory) beanFactory;
//分组文档存入list集合
List<Docket> docketList = new LinkedList<>();
/*
*情况1：没有分组
*/
if (swaggerProperties.getDocket().isEmpty()) {
Docket docket = createDocket(swaggerProperties);
configurableBeanFactory.registerSingleton(swaggerProperties.getTitle(),docket);
docketList.add(docket);
return docketList;
}
/*
*情况2：分组创建
*/
for (String groupName : swaggerProperties.getDocket().keySet()){
//value
SwaggerProperties.DocketInfo docketInfo =
swaggerProperties.getDocket().get(groupName);
ApiInfo apiInfo = new ApiInfoBuilder()
//页面标题
.title(docketInfo.getTitle())
//创建人
.contact(new Contact(docketInfo.getContact().getName(),
docketInfo.getContact().getUrl(),
docketInfo.getContact().getEmail()))
//版本号
.version(docketInfo.getVersion())
//描述
.description(docketInfo.getDescription())
.build();
// base-path处理
// 当没有配置任何path的时候，解析/**
if (docketInfo.getBasePath().isEmpty()) {
docketInfo.getBasePath().add("/**");
}
List<Predicate<String>> basePath = new ArrayList<>();
for (String path : docketInfo.getBasePath()) {
basePath.add(PathSelectors.ant(path));
}
// exclude-path处理
List<Predicate<String>> excludePath = new ArrayList<>();
for (String path : docketInfo.getExcludePath()) {
excludePath.add(PathSelectors.ant(path));
}
Docket docket = new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo)
.groupName(docketInfo.getGroup())
.select()
//为当前包路径
.apis(RequestHandlerSelectors.basePackage(docketInfo.getBasePackage()))
.paths(Predicates.and(Predicates.not(Predicates.or(excludePath)),Predicates.or(basePath)))
.build();
//注册
configurableBeanFactory.registerSingleton(groupName, docket);
docketList.add(docket);
}
return docketList;
}
//构建 api文档的详细信息
private ApiInfo apiInfo(SwaggerProperties swaggerProperties) {
return new ApiInfoBuilder()
//页面标题
.title(swaggerProperties.getTitle())
//创建人
.contact(new Contact(swaggerProperties.getContact().getName(),
swaggerProperties.getContact().getUrl(),
swaggerProperties.getContact().getEmail()))
//版本号
.version(swaggerProperties.getVersion())
//描述
.description(swaggerProperties.getDescription())
.build();
}
//创建接口文档对象
private Docket createDocket(SwaggerProperties swaggerProperties) {
//API 基础信息
ApiInfo apiInfo = apiInfo(swaggerProperties);
// base-path处理
// 当没有配置任何path的时候，解析/**
if (swaggerProperties.getBasePath().isEmpty()) {
swaggerProperties.getBasePath().add("/**");
}
List<Predicate<String>> basePath = new ArrayList<>();
for (String path : swaggerProperties.getBasePath()) {
basePath.add(PathSelectors.ant(path));
}
// exclude-path处理
List<Predicate<String>> excludePath = new ArrayList<>();
for (String path : swaggerProperties.getExcludePath()) {
excludePath.add(PathSelectors.ant(path));
}
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo)
.groupName(swaggerProperties.getGroup())
.select()
.apis(RequestHandlerSelectors.basePackage(swaggerProperties.getBasePackage()))
.paths(Predicates.and(Predicates.not(Predicates.or(excludePath)),Predicates.or(basePath)))
.build();
}
}
7，创建启动类SwaggerDemoApplication
@SpringBootApplication
public class SwaggerDemoApplication {
public static void main(String[] args) {
SpringApplication.run(SwaggerDemoApplication.class, args);
}
}
8，执行启动类main方法启动项目，访问地址：http://localhost:7788/doc.html
注意：如果接口文档不分组，修改application.yml文件：
server:
port: 7788
pinda:
swagger:
enabled: true #是否启用swagger
title: test模块
description: 在线文档
version: 0.1
base-package: cn.ben.controller
# docket:
# user: #Map<String, DocketInfo> docket的key
# title: 用户模块 #Map<String, DocketInfo> docket的value
# base-package: cn.ben.controller.user #Map<String, DocketInfo> docket的value
# menu:
# title: 菜单模块
# base-package: cn.ben.controller.menu
再次访问地址：http://localhost:7788/doc.html。可以看到所有的接口在一个分组中。
自定义starter：pd-tools-swagger2使用
自定义starter：pd-tools-swagger2
在/resources/META-INF中提供spring.factories文件中提供自定配置类：
org.springframework.boot.autoconfigure.EnableAutoConfiguration=\
com.ben.pinda.swagger2.SwaggerAutoConfiguration
自定义starter引入以上笔记中相关类
1,创建配置属性类SwaggerProperties
2,创建配置类SwaggerAutoConfiguration
自定义starter使用
在其他模块中如果需要使用swagger接口文档功能，只需要引入这个starter并且在application.yml中进行swagger的相关配置即可，例如：
pinda:
swagger:
enabled: true #是否启用swagger
docket:
user:
title: 用户模块
base-package: cn.itcast.controller.user
menu:
title: 菜单模块
base-package: cn.itcast.controller.menu
具体使用过程：
1，创建maven工程mySwaggerApp并配置pom.xml
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<parent>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-parent</artifactId>
<version>2.2.2.RELEASE</version>
<relativePath/>
</parent>
<groupId>com.ben</groupId>
<artifactId>mySwaggerApp</artifactId>
<version>1.0-SNAPSHOT</version>
<dependencies>
<!--引入我们自己定义的swagger基础模块-->
<dependency>
<groupId>com.ben</groupId>
<artifactId>pd-tools-swagger2</artifactId>
<version>1.0-SNAPSHOT</version>
</dependency>
<dependency>
<groupId>org.projectlombok</groupId>
<artifactId>lombok</artifactId>
</dependency>
</dependencies>
</project>
2，创建User实体类
@Data
@ApiModel(description = "用户实体")
public class User {
@ApiModelProperty(value = "主键")
private int id;
@ApiModelProperty(value = "姓名")
private String name;
@ApiModelProperty(value = "年龄")
private int age;
@ApiModelProperty(value = "地址")
private String address;
}
3，创建UserController
@RestController
@RequestMapping("/user")
@Api(tags = "用户控制器")
public class UserController {
@GetMapping("/getUsers")
@ApiOperation(value = "查询所有用户", notes = "查询所有用户信息")
public List<User> getAllUsers(){
User user = new User();
user.setId(100);
user.setName("itcast");
user.setAge(20);
user.setAddress("bj");
List<User> list = new ArrayList<>();
list.add(user);
return list;
}
@PostMapping("/save")
@ApiOperation(value = "新增用户", notes = "新增用户信息")
public String save(@RequestBody User user){
return "OK";
}
@PutMapping("/update")
@ApiOperation(value = "修改用户", notes = "修改用户信息")
public String update(@RequestBody User user){
return "OK";
}
@DeleteMapping("/delete")
@ApiOperation(value = "删除用户", notes = "删除用户信息")
public String delete(int id){
return "OK";
}
@ApiImplicitParams({
@ApiImplicitParam(name = "pageNum", value = "页码",
required = true, type = "Integer"),
@ApiImplicitParam(name = "pageSize", value = "每页条数",
required = true, type = "Integer"),
})
@ApiOperation(value = "分页查询用户信息")
@GetMapping(value = "page/{pageNum}/{pageSize}")
public String findByPage(@PathVariable Integer pageNum,
@PathVariable Integer pageSize) {
return "OK";
}
}
4，创建application.yml
server:
port: 8081
pinda:
swagger:
enabled: true
title: 在线接口文档
base-package: com.ben.controller
5，创建启动类
@SpringBootApplication
public class MySwaggerApplication {
public static void main(String[] args) {
SpringApplication.run(MySwaggerApplication.class,args);
}
}
6，启动项目，访问地址：http://localhost:8081/doc.html
总结：
swagger，knife4j（ui界面更清爽）做接口文档
1，自定义swagger起步项目，ConfigurationProperties类主要定义application.yml中配置的属性
2，SwaggerAutoConfiguration类主要利用@EnableConfigurationProperties(SwaggerProperties.class)注解启动配置属性类，@Configuration注解定义自身是一个配置类
@ConditionalOnProperty注解控制接口文档是否开启
3，spring.factories中配置EnableAutoConfiguration=SwaggerAutoConfiguration，完成springboot自动配置
4，在其他模块中如果需要使用swagger接口文档功能，只需要引入这个starter并且在application.yml中进行swagger的相关配置即可
1147
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
