三品达通用权限系统__pd-tools-swagger2
Posted 上善若水
tags:
篇首语：本文由小常识网(cha138.com)小编为大家整理，主要介绍了三品达通用权限系统__pd-tools-swagger2相关的知识，希望对你有一定的参考价值。
一、swagger2
pd-tool-swagger2模块定位为文档组件，前后端开发人员可以查看接口文档，为前后端开发人员的开发统一接口，方便后续的前后端联调对接工作。
1.1、swagger介绍
相信无论是前端还是后端开发，都或多或少地被接口文档折磨过。前端经常抱怨后端给的接口文档与实际情况不一致。后端又觉得编写及维护接口文档会耗费不少精力，经常来不及更新。其实无论是前端调用后端，还是后端调用后端，都期望有一个好的接口文档。但是这个接口文档对于程序员来说，就跟注释一样，经常会抱怨别人写的代码没有写注释，然而自己写起代码起来，最讨厌的，也是写注释。所以仅仅只通过强制来规范大家是不够的，随着时间推移，版本迭代，接口文档往往很容易就跟不上代码了。
使用Swagger你只需要按照它的规范去定义接口及接口相关的信息。再通过Swagger衍生出来的一系列项目和工具，就可以做到生成各种格式的接口文档，生成多种语言的客户端和服务端的代码，以及在线接口调试页面等等。这样，如果按照新的开发模式，在开发新版本或者迭代版本的时候，只需要更新Swagger描述文件，就可以自动生成接口文档和客户端服务端代码，做到调用端代码、服务端代码以及接口文档的一致性。
为了简化swagger的使用，Spring框架对swagger进行了整合，建立了Spring-swagger项目，后面改成了现在的Springfox。通过在项目中引入Springfox，可以扫描相关的代码，生成描述文件，进而生成与代码一致的接口文档和客户端代码。
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>
1.2、swagger常用注解
| 注解 | 说明 |
|---|---|
| @Api | 用在请求的类上，例如Controller，表示对类的说明 |
| @ApiModel | 用在类上，通常是实体类，表示一个返回响应数据的信息 |
| @ApiModelProperty | 用在属性上，描述响应类的属性 |
| @ApiOperation | 用在请求的方法上，说明方法的用途、作用 |
| @ApiImplicitParams | 用在请求的方法上，表示一组参数说明 |
| @ApiImplicitParam | 用在@ApiImplicitParams注解中，指定一个请求参数的各个方面 |
1.3、swagger入门案例
第一步：创建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>com.xbmu</groupId>
<artifactId>swagger_demo</artifactId>
<version>1.0-SNAPSHOT</version>
<properties>
<java.version>1.8</java.version>
</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>
第二步：创建application.yml文件
server:
port: 9000
第三步：创建实体类User和Menu
package com.xbmu.entity;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;
@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;
package com.xbmu.entity;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;
@Data
@ApiModel(description = "菜单实体")
public class Menu
@ApiModelProperty(value = "主键")
private int id;
@ApiModelProperty(value = "名称")
private String name;
第四步：创建UserController和MenuController
package com.xbmu.controller.user;
import com.xbmu.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;
@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("Bob");
user.setAge(18);
user.setAddress("西安");
List<User> userList = new ArrayList<>();
userList.add(user);
return userList;
@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.xbmu.controller.menu;
import com.xbmu.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;
@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("用户管理");
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";
第五步：创建配置类SwaggerAutoConfiguration
package com.xbmu.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;
@Configuration
@EnableSwagger2
public class SwaggerAutoConfiguration
@Bean
public Docket createRestApi1()
Docket docket = new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo()).groupName("用户接口组")
.select()
//为当前包路径
.apis(RequestHandlerSelectors.basePackage("com.xbmu.controller.user"))
.build();
return docket;
@Bean
public Docket createRestApi2()
Docket docket = new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo()).groupName("菜单接口组")
.select()
//为当前包路径
.apis(RequestHandlerSelectors.basePackage("com.xbmu.controller.menu"))
.build();
return docket;
//构建 api文档的详细信息
private ApiInfo apiInfo()
return new ApiInfoBuilder()
//页面标题
.title("API接口文档")
//创建人
.contact(new Contact("btt2013", "https://blog.csdn.net/btt2013", ""))
//版本号
.version("1.0")
//描述
.description("API 描述")
.build();
第六步：创建启动类SwaggerDemoApplication
package com.xbmu;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
@SpringBootApplication
public class SwaggerDemoApplication
public static void main(String[] args)
SpringApplication.run(SwaggerDemoApplication.class, args);
执行启动类main方法启动项目，访问地址：http://localhost:9000/swagger-ui.html
二、knife4j
knife4j是为Java MVC框架集成Swagger生成Api文档的增强解决方案，前身是swagger-bootstrap-ui，取名knife4j是希望它能像一把匕首一样小巧,轻量,并且功能强悍!其底层是对Springfox的封装，使用方式也和Springfox一致，只是对接口文档UI进行了优化。
2.1、knife4j介绍
核心功能：
- 文档说明：根据Swagger的规范说明，详细列出接口文档的说明，包括接口地址、类型、请求示例、请求参数、响应示例、响应参数、响应码等信息，对该接口的使用情况一目了然。
- 在线调试：提供在线接口联调的强大功能，自动解析当前接口参数,同时包含表单验证，调用参数可返回接口响应内容、headers、响应时间、响应状态码等信息，帮助开发者在线调试。
2.2、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/>
&l以上是关于三品达通用权限系统__pd-tools-swagger2的主要内容，如果未能解决你的问题，请参考以下文章