目录 1、swagger介绍 2、swagger常用注解 3、 swagger入门案例 4、knife4j介绍 5、knife4j入门案例 总结 入门级swagger2和knife4j的详细使用 重要的使事情说三遍 重要的使事情说三遍 重要的使事情说
目录
- 1、swagger介绍
- 2、swagger常用注解
- 3、 swagger入门案例
- 4、knife4j介绍
- 5、knife4j入门案例
- 总结
入门级swagger2和knife4j的详细使用
重要的使事情说三遍
重要的使事情说三遍
重要的使事情说三遍
使用swagge或knife4j都有与springboot的版本兼容问题，该文章使用的springboot版本是2.2.2.RELEASE版本，如果高版本可能会出现启动报错
1、swagger介绍
相信无论是前端还是后端开发，都或多或少地被接口文档折磨过。前端经常抱怨后端给的接口文档与实际情况不一致。后端又觉得编写及维护接口文档会耗费不少精力，经常来不及更新。其实无论是前端调用后端，还是后端调用后端，都期望有一个好的接口文档。但是这个接口文档对于程序员来说，就跟注释一样，经常会抱怨别人写的代码没有写注释，然而自己写起代码起来，最讨厌的，也是写注释。所以仅仅只通过强制来规范大家是不够的，随着时间推移，版本迭代，接口文档往往很容易就跟不上代码了。
使用Swagger你只需要按照它的规范去定义接口及接口相关的信息。再通过Swagger衍生出来的一系列项目和工具，就可以做到生成各种格式的接口文档，生成多种语言的客户端和服务端的代码，以及在线接口调试页面等等。这样，如果按照新的开发模式，在开发新版本或者迭代版本的时候，只需要更新Swagger描述文件，就可以自动生成接口文档和客户端服务端代码，做到调用端代码、服务端代码以及接口文档的一致性。
为了简化swagger的使用，Spring框架对swagger进行了整合，建立了Spring-swagger项目，后面改成了现在的Springfox。通过在项目中引入Springfox，可以扫描相关的代码，生成描述文件，进而生成与代码一致的接口文档和客户端代码。
Springfox对应的maven坐标如下：
注意：swagger与springBoot的版本是有兼用性的，需要对应的版本号
<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>
2、swagger常用注解
3、 swagger入门案例
3.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 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>org.example</groupId>
<artifactId>swagger_demo</artifactId>
<version>1.0-SNAPSHOT</version>
<properties>
<maven.compiler.source>8</maven.compiler.source>
<maven.compiler.target>8</maven.compiler.target>
</properties>
<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
<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>
<dependency>
<groupId>org.projectlombok</groupId>
<artifactId>lombok</artifactId>
</dependency>
</dependencies>
</project>
3.2、创建application.yml文件
server: port: 9000
3.3、第三步： 创建实体类User和Menu
package com.zcl.entity;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;
/**
* 项目名称：swagger_demo
* 描述：用户实体类
*
* @author zhong
* @date 2022-08-29 6:50
*/
@Data
@ApiModel(value = "用户实体",description = "用户响应实体")
public class User {
@ApiModelProperty(value = "主键")
private int id;
@ApiModelProperty(value = "姓名")
private String name;
@ApiModelProperty(value = "年龄")
private int age;
@ApiModelProperty(value = "地址")
private String address;
}
package com.zcl.entity;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;
/**
* 项目名称：swagger_demo
* 描述：菜单实体类
*
* @author zhong
* @date 2022-08-29 6:49
*/
@Data
@ApiModel(value = "菜单实体",discriminator = "菜单实体描述")
public class Menu {
@ApiModelProperty(value = "主键")
private int id;
@ApiModelProperty(value = "菜单名称")
private String name;
}
3.4、第四步：创建UserController和MenuController
package com.zcl.controller.user;
import com.zcl.entity.User;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.*;
import java.util.ArrayList;
import java.util.List;
/**
* 项目名称：swagger_demo
* 描述：用户控制器
*
* @author zhong
* @date 2022-08-29 6:55
*/
@Api(value = "用户控制器")
@RestController
@RequestMapping("/user")
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";
}
}
package com.zcl.controller.menu;
import com.zcl.entity.Menu;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.*;
import java.util.ArrayList;
import java.util.List;
/**
* 项目名称：swagger_demo
* 描述：菜单控制器
*
* @author zhong
* @date 2022-08-29 7:00
*/
@Api(tags = "菜单控制器")
@RestController
@RequestMapping("/menu")
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";
}
}
3.5、第五步：创建配置类SwaggerAutoConfiguration
package com.zcl.config;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
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;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
/**
* 项目名称：swagger_demo
* 描述：swagger自动配置类
*
* @author zhong
* @date 2022-08-29 7:04
*/
@Configuration
@EnableSwagger2
public class SwaggerAutoConfiguration {
@Bean
public Docket createRestApi1() {
Docket docket = new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo()).groupName("用户接口组")
.select()
//为当前包路径
.apis(RequestHandlerSelectors.basePackage("com.zcl.controller.user"))
.build();
return docket;
}
@Bean
public Docket createRestApi2() {
Docket docket = new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo()).groupName("菜单接口组")
.select()
//为当前包路径
.apis(RequestHandlerSelectors.basePackage("com.zcl.controller.menu"))
.build();
return docket;
}
//构建 api文档的详细信息
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
//页面标题
.title("API接口文档")
//创建人
.contact(new Contact("雕刻笔记", "http://xiaozhong01.top", ""))
//版本号
.version("1.0")
//描述
.description("API 描述")
.build();
}
}
注意：如果不需要进行分组，可以将后面的createRestApi2()进行删除就剩余一个组了，并将.groupName("用户接口组")分组描述去掉以及将扫描控制器包修改即可
3.6、第六步：创建启动类SwaggerApplication
package com.zcl;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
/**
* 项目名称：swagger_demo
* 描述：swagger项目启动类
*
* @author zhong
* @date 2022-08-29 7:13
*/
@SpringBootApplication
public class SwaggerApplication {
public static void main(String[] args) {
SpringApplication.run(SwaggerApplication.class,args);
}
}
3.7、项目启动
执行启动类main方法启动项目，访问地址：http://localhost:9000/swagger-ui.html
4、knife4j介绍
knife4j是为Java MVC框架集成Swagger生成Api文档的增强解决方案,前身是swagger-bootstrap-ui,取名knife4j是希望它能像一把匕首一样小巧,轻量,并且功能强悍!其底层是对Springfox的封装，使用方式也和Springfox一致，只是对接口文档UI进行了优化。
核心功能：
- 文档说明：根据Swagger的规范说明，详细列出接口文档的说明，包括接口地址、类型、请求示例、请求参数、响应示例、响应参数、响应码等信息，对该接口的使用情况一目了然。
- 在线调试：提供在线接口联调的强大功能，自动解析当前接口参数,同时包含表单验证，调用参数可返回接口响应内容、headers、响应时间、响应状态码等信息，帮助开发者在线调试。
5、knife4j入门案例
第一步：创建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>org.example</groupId>
<artifactId>knife4j</artifactId>
<version>1.0-SNAPSHOT</version>
<properties>
<maven.compiler.source>8</maven.compiler.source>
<maven.compiler.target>8</maven.compiler.target>
</properties>
<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>
第二步： 创建实体类User和Menu
package com.zcl.entity;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;
/**
* 项目名称：swagger_demo
* 描述：菜单实体类
*
* @author zhong
* @date 2022-08-29 6:49
*/
@Data
@ApiModel(value = "菜单实体",discriminator = "菜单实体描述")
public class Menu {
@ApiModelProperty(value = "主键")
private int id;
@ApiModelProperty(value = "菜单名称")
private String name;
}
package com.zcl.entity;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;
/**
* 项目名称：swagger_demo
* 描述：用户实体类
*
* @author zhong
* @date 2022-08-29 6:50
*/
@Data
@ApiModel(value = "用户实体",description = "用户响应实体")
public class User {
@ApiModelProperty(value = "主键")
private int id;
@ApiModelProperty(value = "姓名")
private String name;
@ApiModelProperty(value = "年龄")
private int age;
@ApiModelProperty(value = "地址")
private String address;
}
第三步：创建UserController和MenuController
控制器与入门的swagger2是一样的，直接复制下来
第四步：创建接口文档配置属性类SwaggerProperties
由于上一个
swagger_demo的接口文档配置文件是写死在项目代码中的，不利于后面的开发与维护，使用knife4j时并将相关的属性配置以yml全局的方式灵活的进行配置，方便进行修改
package com.zcl.config;
import lombok.Data;
import org.springframework.boot.context.properties.ConfigurationProperties;
import java.util.ArrayList;
import java.util.LinkedHashMap;
import java.util.List;
import java.util.Map;
/**
* 项目名称：knife4j
* 描述：配置属性类，用于封装yml配置文件中关于接口相关的配置文件
*
* @author zhong
* @date 2022-08-29 7:58
*/
@Data
@ConfigurationProperties(prefix = "knife.swagger")
public class SwaggerProperties {
/**标题*/
private String title = "在线文档";
/**自定义组名*/
private String group = "";
/**描述*/
private String description = "在线文档";
/**版本*/
private String version = "1.0";
/**联系人*/
private Contact contact = new Contact();
/**swagger会解析的包路径*/
private String basePackage = "com.zcl";
/**swagger会解析的url规则*/
private List<String> basePath = new ArrayList<>();
/**在basePath基础上需要排除的url规则*/
private List<String> excludePath = new ArrayList<>();
/**分组文档*/
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();
/**swagger会解析的包路径*/
private String basePackage = "com.zcl";
/**swagger会解析的url规则*/
private List<String> basePath = new ArrayList<>();
/**在basePath基础上需要排除的url规则*/
private List<String> excludePath = new ArrayList<>();
/**分组文档*/
private Map<String, DocketInfo> docket = new LinkedHashMap<>();
public String getGroup() {
if (group == null || "".equals(group)) {
return title;
}
return group;
}
}
@Data
public static class Contact {
/**联系人*/
private String name = "pinda";
/**联系人url*/
private String url = "";
/**联系人email*/
private String email = "";
}
}
第五步：创建application.yml文件
该配置文件的属性是对应上面的配置文件属性的如果不对上就不会被读取到
下面重点的是对【docket】进行map分组的属性配置
private Map<String, DocketInfo> docket = new LinkedHashMap<>();
不进行分组的配置
server:
port: 7788
knife:
swagger:
enabled: true #是否启用swagger的开关
title: knife4j测试文档
description: knife4j测试文档描述
version: v1.0.0
basePackage: com.zcl.controller
进行分组的配置
server:
port: 7788
knife:
swagger:
enabled: true #是否启用swagger的开关
title: knife4j测试文档
description: knife4j测试文档描述
version: v1.0.0
docket: # 进行分组
user: # key
# value
title: 用户模块
base-package: com.zcl.controller.user
menu:
title: 菜单模块
base-package: com.zcl.controller.menu
注意：上面配置文件中的enabled属性是对应着下面配置类中【@ConditionalOnProperty】通过注解判断是否符合条件才让配置类生效
第六步：创建配置类SwaggerAutoConfiguration
该配置类需要使到上面创建的
SwaggerProperties生效以及需要启用swagger注解
package com.zcl.config;
import com.google.common.base.Predicate;
import com.google.common.base.Predicates;
import org.springframework.beans.BeansException;
import org.springframework.beans.factory.BeanFactory;
import org.springframework.beans.factory.BeanFactoryAware;
import org.springframework.beans.factory.config.ConfigurableBeanFactory;
import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
import org.springframework.boot.context.properties.EnableConfigurationProperties;
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;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
import javax.annotation.Resource;
import java.util.ArrayList;
import java.util.List;
import java.util.Map;
import java.util.Set;
/**
* 项目名称：knife4j
* 描述：配置类
*
* @author zhong
* @date 2022-08-29 8:22
*/
@Configuration
@EnableConfigurationProperties(SwaggerProperties.class)
@EnableSwagger2
@ConditionalOnProperty(name = "knife.swagger.enabled", havingValue = "true",
matchIfMissing = true)
public class SwaggerAutoConfiguration implements BeanFactoryAware {
private BeanFactory beanFactory;
/**
* 通过类型注入去查找beanFactory
* @param beanFactory
* @throws BeansException
*/
@Override
public void setBeanFactory(BeanFactory beanFactory) throws BeansException {
this.beanFactory = beanFactory;
}
/**
* 注入自动配置属性类
*/
@Resource
private SwaggerProperties swaggerProperties;
/**
* 遍历swaggerProperties属性配置的内容，转换成List集合【方便判断有没有进行分组，没有分组就一个list，分组就有多个】
* 使用@ConditionalOnProperty条件注入，bean工程有就不创建
* @return
*/
@Bean
@ConditionalOnMissingBean
public List<Docket> createRestApi() {
// 强转beanFactory为可配置的bean工厂
ConfigurableBeanFactory configurableBeanFactory =
(ConfigurableBeanFactory) beanFactory;
// 创建返回的list集合
List<Docket> docketList = new ArrayList<>();
// 获取到分组的对象如果为空就是不分组
if(swaggerProperties.getDocket().isEmpty()){
Docket docket = createDocket(swaggerProperties);
docketList.add(docket);
}else{
// 存在分组对象
// 获取到key【user\menu】
Set<String> keySet = swaggerProperties.getDocket().keySet();
// 遍历key获取到对应的value
for (String key : keySet) {
// 获取到info
SwaggerProperties.DocketInfo docketInfo = swaggerProperties.getDocket().get(key);
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(key, docket);
docketList.add(docket);
}
}
return docketList;
}
/**
* 构建 api文档的详细信息
* @param swaggerProperties
* @return
*/
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();
}
/**
* 创建接口文档对象
* @param swaggerProperties 属性配置
* @return
*/
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();
}
}
第七步：创建启动类knife4jApplication
package com.zcl;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
/**
* 项目名称：knife4j
* 描述：knife4j项目启动类
*
* @author zhong
* @date 2022-08-29 8:09
*/
@SpringBootApplication
public class knife4jApplication {
public static void main(String[] args) {
SpringApplication.run(knife4jApplication.class, args);
}
}
执行启动类main方法启动项目，访问地址：http://localhost:7788/doc.html
总结
到此这篇关于swagger2和knife4j的详细使用教程的文章就介绍到这了,更多相关swagger2和knife4j使用内容请搜索自由互联以前的文章或继续浏览下面的相关文章希望大家以后多多支持自由互联！