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得一塌糊涂，有没有！