1、什么是swagger2
swagger是一个在线文档工具，在前后端分离的情况下作用愈加突出，使用swagger我们可以针对我们在后端的接口做一个在线测试。
编写和维护接口文档是每个程序员的职责，根据Swagger2可以快速帮助我们编写最新的API接口文档，再也不用担心开会前仍忙于整理各种资料了，间接提升了团队开发的沟通效率。
2、简单地使用swagger2只需要三步:
第一步，配置pom文件。在pom文件中引入swagger的相关依赖,2.9.2版本使用的比较多
<!--swagger -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<!--swagger-ui.html模式 -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
<!--doc.html模式 -->
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>swagger-bootstrap-ui</artifactId>
<version>1.9.2</version>
</dependency>
注意：swagger的访问地址有两种样式，此处将两种样式的依赖都进行了导入，样式如下图：
第二步，配置pom文件创建Swagger的配置类，并进行配置
此类放在config包下：
package com.fan.mybatis_plus1.config;
import io.swagger.annotations.ApiOperation;
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;
/**
* @Author: zq
* @Date 2020-08-24 10:55
* @Description swagger 配置类，swagger基本信息和接口的权限
* @ClassName SwaggerConfig
* @PackageName com.zq.springboot.common.config
*/
@Configuration
@EnableSwagger2
public class SwaggerConfig {
/**
* 创建api实例
* @return
*/
@Bean
public Docket createRestAoi(){
return new Docket(DocumentationType.SWAGGER_2)
//用来创建该API的基本信息，展示在文档的页面中（自定义展示的信息）
.apiInfo(apiInfo())
//设置哪些接口暴露给Swagger展示
.select()
//扫描所有有注解的api，用这种方式更灵活，指定为ApiOperation.class
.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
//构建
.build();
}
/**
* 添加摘要信息
* @return
*/
private ApiInfo apiInfo(){
//用ApiInfoBuilder进行定制，可以设置不同的属性，比较方便
return new ApiInfoBuilder()
//设置标题
.title("标题：springboot集成swagger测试")
//描述
.description("描述：用于测试集成swagger接口")
//作者信息
.contact(new Contact("zq",null,null))
//版本
.version("版本号：1.0")
//构建
.build();
}
}
第三步、使用注解
@Api 标识一个java类型是文档类，用controller类的类名上
@ApiModel 表示一个实体类/模型文档，用在类名上；
@ApiModelProperty 作用在属性上，添加属性描述；
@ApiOperation 作用在接口类的方法上，控制方法的相关描述；
@ApiImplicitParam 作用在接口方法上，描述单个参数信息，只能作用在方法上；
@ApiImplicitParams 作用在接口方法上，@ApiImplicitParam参数组；
@ApiParam 作用在接口方法上，描述单个参数信息，属性基本与@ApiImplicitParam一样，但可以作用在方法、参数、属性上；
3、SpringBoot整合Swagger实战
(1)创建springboot项目：
其他都是下一步即可。
(2)修改pom:增加web依赖和swagger相关依赖
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
<!--mysql驱动-->
<dependency>
<groupId>mysql</groupId>
<artifactId>mysql-connector-java</artifactId>
<version>8.0.22</version>
</dependency>
<!--mybais_plus-->
<dependency>
<groupId>com.baomidou</groupId>
<artifactId>mybatis-plus-boot-starter</artifactId>
<version>3.4.2</version>
</dependency>
<!--代码生成器-->
<dependency>
<groupId>com.baomidou</groupId>
<artifactId>mybatis-plus-generator</artifactId>
<version>3.4.1</version>
</dependency>
<!-- 添加 模板引擎 依赖 -->
<dependency>
<groupId>org.apache.velocity</groupId>
<artifactId>velocity-engine-core</artifactId>
<version>2.2</version>
</dependency>
<!--swagger -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<!--swagger-ui.html模式 -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
<!--doc.html模式 -->
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>swagger-bootstrap-ui</artifactId>
<version>1.9.2</version>
</dependency>
<dependency>
<groupId>org.projectlombok</groupId>
<artifactId>lombok</artifactId>
</dependency>
创建数据库的表：stutest
(3)编写yml:
server:
port: 8080
spring:
datasource:
driver-class-name: com.mysql.cj.jdbc.Driver
url: jdbc:mysql://127.0.0.1:3306/mybatis_plus?useUnicode=true&characterEncoding=utf-8&allowMultiQueries=true&useSSL=false&serverTimezone=UTC
username: root
password: root
mvc:
pathmatch:
matching-strategy: ant_path_matcher
#sql输出日志
mybatis-plus:
configuration:
log-impl: org.apache.ibatis.logging.stdout.StdOutImpl
(4)编写代码生成器的类：类路径util.CodeGenerator,
如果不用MP的代码生成器，也可以自己创建controller,mapper,server,entity等。
package com.fan.springboot_swagger.util;
import com.baomidou.mybatisplus.annotation.FieldFill;
import com.baomidou.mybatisplus.annotation.IdType;
import com.baomidou.mybatisplus.core.exceptions.MybatisPlusException;
import com.baomidou.mybatisplus.generator.AutoGenerator;
import com.baomidou.mybatisplus.generator.config.DataSourceConfig;
import com.baomidou.mybatisplus.generator.config.GlobalConfig;
import com.baomidou.mybatisplus.generator.config.PackageConfig;
import com.baomidou.mybatisplus.generator.config.StrategyConfig;
import com.baomidou.mybatisplus.generator.config.po.TableFill;
import com.baomidou.mybatisplus.generator.config.rules.DateType;
import com.baomidou.mybatisplus.generator.config.rules.NamingStrategy;
import org.apache.commons.lang3.StringUtils;
import java.util.ArrayList;
import java.util.Scanner;
public class CodeGenerator {
public static String scanner(String tip) {
Scanner scanner = new Scanner(System.in);
StringBuilder help = new StringBuilder();
help.append("请输入" + tip + "：");
System.out.println(help.toString());
if (scanner.hasNext()) {
String ipt = scanner.next();
if (StringUtils.isNotBlank(ipt)) {
return ipt;
}
}
throw new MybatisPlusException("请输入正确的" + tip + "！");
}
public static void main(String[] args) {
// 代码生成器
AutoGenerator mpg = new AutoGenerator();
// 全局配置
GlobalConfig gc = new GlobalConfig();
String projectPath = System.getProperty("user.dir");//用户路径,不用修改
gc.setOutputDir(projectPath + "/src/main/java");//设置代码生成路径：用户路径+/src/main/java
gc.setFileOverride(true);//是否覆盖以前文件
gc.setOpen(false);//是否打开生成目录
gc.setAuthor("fan");//设置项目作者名称
gc.setIdType(IdType.ASSIGN_ID);//设置主键策略,IdType.ASSIGN_ID使用了雪花算法，比较好
gc.setBaseResultMap(true);//生成基本ResultMap
gc.setBaseColumnList(true);//生成基本ColumnList
gc.setServiceName("%sService");//去掉服务默认前缀
gc.setDateType(DateType.ONLY_DATE);//设置时间类型
mpg.setGlobalConfig(gc);
// 数据源配置
DataSourceConfig dsc = new DataSourceConfig();
dsc.setUrl("jdbc:mysql://localhost:3306/mybatis_plus?useUnicode=true&characterEncoding=utf-8&serverTimezone=GMT%2B8");
dsc.setDriverName("com.mysql.cj.jdbc.Driver");
dsc.setUsername("root");
dsc.setPassword("root");
mpg.setDataSource(dsc);
// 包配置
PackageConfig pc = new PackageConfig();
pc.setParent("com.fan.mybatis_plus1");
pc.setMapper("mapper");
pc.setXml("mapper.xml");
pc.setEntity("pojo");
pc.setService("service");
pc.setServiceImpl("service.impl");
pc.setController("controller");
mpg.setPackageInfo(pc);
// 策略配置
StrategyConfig sc = new StrategyConfig();
sc.setNaming(NamingStrategy.underline_to_camel);
sc.setColumnNaming(NamingStrategy.underline_to_camel);
sc.setEntityLombokModel(true);//自动lombok
sc.setRestControllerStyle(true);
sc.setControllerMappingHyphenStyle(true);
sc.setLogicDeleteFieldName("deleted");//设置逻辑删除
//设置自动填充配置
TableFill gmt_create = new TableFill("create_time", FieldFill.INSERT);
TableFill gmt_modified = new TableFill("update_time", FieldFill.INSERT_UPDATE);
ArrayList<TableFill> tableFills=new ArrayList<>();
tableFills.add(gmt_create);
tableFills.add(gmt_modified);
sc.setTableFillList(tableFills);
//乐观锁
sc.setVersionFieldName("version");
sc.setRestControllerStyle(true);//驼峰命名
// sc.setTablePrefix("tbl_"); 设置表名前缀
sc.setInclude(scanner("表名，多个英文逗号分割").split(","));
mpg.setStrategy(sc);
// 生成代码
mpg.execute();
}
}
(5)修改代码生成器部分代码：
(6)运行main方法，输入表名即可，生成效果：
(7)swagger配置类：
package com.fan.mybatis_plus1.config;
import io.swagger.annotations.ApiOperation;
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;
/**
* @Author: zq
* @Date 2020-08-24 10:55
* @Description swagger 配置类，swagger基本信息和接口的权限
* @ClassName SwaggerConfig
* @PackageName com.zq.springboot.common.config
*/
@Configuration
@EnableSwagger2
@MapperScan("com.fan.springboot_swagger.mapper") //增加mapper包的扫描
public class SwaggerConfig {
/**
* 创建api实例
* @return
*/
@Bean
public Docket createRestAoi(){
return new Docket(DocumentationType.SWAGGER_2)
//用来创建该API的基本信息，展示在文档的页面中（自定义展示的信息）
.apiInfo(apiInfo())
//设置哪些接口暴露给Swagger展示
.select()
//扫描所有有注解的api，用这种方式更灵活，指定为ApiOperation.class
.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
//构建
.build();
}
/**
* 添加摘要信息
* @return
*/
private ApiInfo apiInfo(){
//用ApiInfoBuilder进行定制，可以设置不同的属性，比较方便
return new ApiInfoBuilder()
//设置标题
.title("标题：springboot集成swagger测试")
//描述
.description("描述：用于测试集成swagger接口")
//作者信息
.contact(new Contact("zq",null,null))
//版本
.version("版本号：1.0")
//构建
.build();
}
}
然后启动项目，看是否报错。
测试swagger:注意修改成自己的端口号：
浏览器输入：http://localhost:8080/swagger-ui.html
测试：
给数据库增加数据进行测试：
4、swagger常用注解详解:
@Api 标识一个java类型是文档类，用controller类的类名上
@ApiModel 表示一个实体类/模型文档，用在类名上；
@ApiModelProperty 作用在属性上，添加属性描述；
@ApiOperation 作用在接口类的方法上，控制方法的相关描述；
@ApiImplicitParam 作用在接口方法上，描述单个参数信息，只能作用在方法上；
@ApiImplicitParams 作用在接口方法上，@ApiImplicitParam参数组；
@ApiParam 作用在接口方法上，描述单个参数信息，属性基本与@ApiImplicitParam一样，但可以作用在方法、参数、属性上；
@Api(tags = "学生管理相关接口")
@RestController //@Controller + @ResponseBody
@RequestMapping("/student")
public class StudentAction {
@Autowired
private StudentService studentService;
@ApiOperation("添加一名学生")// 为每个handler添加方法功能描述
@PostMapping("/add_student.action")
@ApiImplicitParam(name = "student", value = "所添加的学生", dataTypeClass = Student.class)
public ResponseVo<Integer> addOneStudent(Student student) {
return studentService.addOneStudent(student);
}
@ApiOperation("根据studentId删除一名学生")
@DeleteMapping("/delete_student/{studentId}.action")
public ResponseVo<Integer> deleteOneStudentByStudentId(@PathVariable Integer studentId) {
return studentService.deleteOneStudentByStudentId(studentId);
}
@ApiOperation("修改一名学生")
@PutMapping("/update_student.action")
@ApiImplicitParams({
@ApiImplicitParam(name = "studentId", value = "学号", required = true), //required为是否必填项
@ApiImplicitParam(name = "studentName", value = "学生姓名", required = false),
@ApiImplicitParam(name = "studentSex", value = "学生性别", required = false),
@ApiImplicitParam(name = "studentScore", value = "学生分数", required = false)
})
public ResponseVo<Integer> updateOneStudent(Student student) {
return studentService.updateOneStudent(student);
}
@ApiOperation("根据id获取一名学生")
@GetMapping("/get_ont_student/{studentId}.action")
public ResponseVo<Student> getOntStudentByStudentId(@PathVariable Integer studentId) {
return studentService.getOneStudentByStudentId(studentId);
}
@ApiOperation("获取全部学生")
@GetMapping("/get_all_student.action")
public ResponseVo<Collection<Student>> getAllStudent() {
return studentService.getAllStudent();
}
(8)我自己的controller测试：
package com.fan.springboot_swagger.controller;
import com.fan.springboot_swagger.pojo.Stutest;
import com.fan.springboot_swagger.service.StutestService;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.web.bind.annotation.*;
import javax.annotation.Resource;
/**
* <p>
* 前端控制器
* </p>
*
* @author fan
* @since 2022-07-20
*/
@RestController
@RequestMapping("/stutest")
@Api("控制器类")
public class StutestController {
@Resource
private StutestService stutestService;
@ApiOperation("根据id查询")
@GetMapping("/getById/{id}")
public Stutest getById(@ApiParam(name = "id",required = true) @PathVariable("id") Long id){
Stutest byId = stutestService.getById(id);
return byId;
}
}
测试：
或者使用这个：http://localhost:8080/doc.html
5、遇到问题总结
7303
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
