Swagger2 是传说中的api文档管理利器，我们一起来学习下如何在sb2中集成swagger2
1.新建一个sb项目
依赖选择Web、LomBok 依赖，（JPA 和 Mysql）可选，系统自动生成的 Pom文件中没有swagger相关的配置，所以需要手动加入：
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.4.0</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.4.0</version>
</dependency>
有时候还需要加入maven-surefire-plugin，防test报错
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-surefire-plugin</artifactId>
<version>2.22.1</version>
<configuration>
<skipTests>true</skipTests>
</configuration>
</plugin>
最后的pom文件长成这样：
<?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.4.2</version>
<relativePath/> <!-- lookup parent from repository -->
</parent>
<groupId>com.study</groupId>
<artifactId>sb4</artifactId>
<version>0.0.1-SNAPSHOT</version>
<name>sb4</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-data-jpa</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
<dependency>
<groupId>mysql</groupId>
<artifactId>mysql-connector-java</artifactId>
<scope>runtime</scope>
</dependency>
<dependency>
<groupId>org.projectlombok</groupId>
<artifactId>lombok</artifactId>
<optional>true</optional>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-test</artifactId>
<scope>test</scope>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.4.0</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.4.0</version>
</dependency>
</dependencies>
<build>
<plugins>
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
<configuration>
<excludes>
<exclude>
<groupId>org.projectlombok</groupId>
<artifactId>lombok</artifactId>
</exclude>
</excludes>
</configuration>
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-surefire-plugin</artifactId>
<version>2.22.1</version>
<configuration>
<skipTests>true</skipTests>
</configuration>
</plugin>
</plugins>
</build>
</project>
如果选了jpa和mysql，那么要在application.properties上加上如下配置：
spring.datasource.url=jdbc:mysql://localhost:3306/test
spring.datasource.username=yourname
spring.datasource.password=yourcode
spring.datasource.driver-class-name=com.mysql.cj.jdbc.Driver
2.在 SpringBoot 启动类（Application）的同级目录新建一个 Swagger 配置类，
注意 Swagger2 配置类必须与项目入口类 Application 位于同一级目录，否则生成 Api 文档失败，代码如下：
package com.study.sb4;
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;
//Swagger 配置类
@Configuration
// 启用 Swagger2
@EnableSwagger2
public class Swagger2 {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
// 文档信息对象
.apiInfo(apiInfo())
.select()
// 被注解的包路径
.apis(RequestHandlerSelectors.basePackage("com.study.sb4.controller"))
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
// 标题
.title("springboot 利用 swagger 构建 API 文档")
// Api 文档描述
.description("简单优雅的 restful 风格，https://amyflash.com")
.termsOfServiceUrl("https://blog.csdn.net/turodog/")
// 文档作者信息
.contact(new Contact("harriet", "https://github.com/amyflash", "nbllq@qq.com"))
// 文档版本
.version("1.0")
.build();
}
}
3.配置被注解的 Controller 类
编写各个接口的请求参数，返回结果，接口描述等等，代码如下：
package com.study.sb4.controller;
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 springfox.documentation.annotations.ApiIgnore;
@RestController
@RequestMapping("/test")
// @Api：修饰整个类，描述Controller的作用
@Api("TestController Api 接口文档")
public class TestController {
// 使用该注解忽略这个API
@ApiIgnore
@RequestMapping(value = "/hi", method = RequestMethod.GET)
public String jsonTest() {
return " hi you!";
}
// @ApiOperation：描述一个类的一个方法，或者说一个接口
@ApiOperation(value="无参get", notes="获取test")
@RequestMapping(value={""}, method= RequestMethod.GET)
public String getTest() {
return "test get without param";
}
@ApiOperation(value="带参get", notes="根据id来获取test详细信息")
@ApiImplicitParam(name = "id", value = "ID", required = true, dataType = "Integer",paramType = "path")
@GetMapping("/{id}")
public String findById(@PathVariable("id") Integer id){
return "this is get id:"+id;
}
@ApiOperation(value="post一个参数", notes="postxx信息")
// @ApiImplicitParam：一个请求参数
@ApiImplicitParam(name = "param", value = "param", required = true, dataType = "String")
//发送post请求
@PostMapping("/p1")
public String postTest1(@RequestBody String param){
return "this is post one param :"+param;
}
/*@ApiOperation(value="删除学生", notes="根据url的id来指定删除的学生")
@ApiImplicitParam(name = "id", value = "学生ID", required = true, dataType = "Integer",paramType = "path")
@DeleteMapping("/{id}")
public String deleteById(@PathVariable("id") Integer id){
studentService.delete(id);
return "success";
}*/
/* @ApiOperation(value="更新学生信息", notes="根据url的id来指定更新学生信息")
// @ApiImplicitParams：多个请求参数
@ApiImplicitParams({
@ApiImplicitParam(name = "id", value = "学生ID", required = true, dataType = "Integer",paramType = "path"),
@ApiImplicitParam(name = "student", value = "学生实体student", required = true, dataType = "Student")
})
@PutMapping(value="/{id}")
public String updateStudent(@PathVariable Integer id, @RequestBody Student student) {
Student oldStudent = this.findById(id);
oldStudent.setId(student.getId());
oldStudent.setName(student.getName());
oldStudent.setAge(student.getAge());
studentService.save(oldStudent);
return "success";
}*/
}
4.启动项目
访问 http://localhost:8080/swagger-ui.html 地址，api文档就自动写好啦，nb得一塌糊涂，有没有！