【SpringBoot】整合Swagger 接口文档

前言

可能运用的开发模式：

SSM -> SpringMVC + Spring + Mybatis

SSMP -> SpringMVC + Spring + MybatisPlus

SM -> SpringBoot + Mybatis

SMP -> SpringBoot + MybatisPlus

分布式

微服务

前后端分离

 

网站架构基本都由原来的后端渲染，变成了：前端渲染、前后端分离的形态，

而且前端技术和后端技术在各自的道路上越走越远。

 

前端和后端的唯一联系，变成了API接口；

API文档变成了前后端开发人员联系的纽带，变得越来越重要，

swagger就是一款让你更好的书写API文档的框架，而且swagger可以完全模拟http请求，入参出参和实际情况差别几乎为零。

没有API文档工具之前，大家都是手写API文档的（维护起来相当困难），

在什么地方书写的都有，有在confluence上写的，有在对应的项目目录下readme.md上写的，

每个公司都有每个公司的玩法，无所谓好坏。

但是能称之为“框架”的，估计也只有swagger了

快速上手：

创建SpringBoot工程：

 

点选常用三件套辅助工具和一个SpringWeb

 

构建完成删除maven的配置文件：

 

 

创建一个user类并放在domain包下

package cn.echo42.domain;

import com.fasterxml.jackson.annotation.JsonFormat;
import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.NoArgsConstructor;
import org.springframework.format.annotation.DateTimeFormat;

import java.util.Date;

/**
 * @author DaiZhiZhou
 * @file SpringBoot-Swagger
 * @create 2020-08-05 10:51
 */

@Data
@AllArgsConstructor
@NoArgsConstructor
public class User {

    private Integer user_id;
    private String user_name;
    private String user_address;

    @DateTimeFormat(pattern = "yyyy-MM-dd")
    @JsonFormat(pattern = "yyyy-MM-dd", timezone = "Asia/Shanghai")
    private Date birth;

}

创建一个结果对象类并放在Common包下：

package cn.echo42.common;

import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.NoArgsConstructor;

/**
 * @author DaiZhiZhou
 * @file SpringBoot-Swagger
 * @create 2020-08-05 10:54
 */

@Data
@AllArgsConstructor
@NoArgsConstructor
public class ResultObject {
    private Integer status = 200;
    private Object msg;
}

集成Swagger2的坐标：

        <!-- swagger -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
        </dependency>
        <!-- swagger-ui -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.9.2</version>
        </dependency>

创建Swagger2的配置类：

package cn.echo42.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 DaiZhiZhou
 * @file SpringBoot-Swagger
 * @create 2020-08-05 10:56
 */
@Configuration
@EnableSwagger2
public class Swagger2Configuration {

    @Bean
    public Docket swaggerSpringMvcPlugin() {
        return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo()).select()
            .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class)).build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
            .description("这是一个很NB的API工具")
            .contact(new Contact("Echo42", "http://www.echo42.cn", "1791255334@qq.com"))  //名片
            .version("1.0")  //版本
            .license("Otaku ArkD42")//所有者
            .build();//构造
    }
}

创建UserController控制器类：

package cn.echo42.controller;

import cn.echo42.common.ResultObject;
import cn.echo42.domain.User;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.*;

import java.util.ArrayList;
import java.util.Date;
import java.util.List;

/**
 * @author DaiZhiZhou
 * @file SpringBoot-Swagger
 * @create 2020-08-05 11:02
 */

@Controller
@RequestMapping("user")
@Api(description = "用户管理",value = "UserController")
public class UserController {

    @ApiOperation(value ="用户查询" ,consumes = "查询所有用户")
    @GetMapping("queryAllUser")
    public List<User> queryAllUser(){
        List<User> list=new ArrayList<>();
        for (int i = 1; i <=5 ; i++) {
            list.add(new User(1,"小明"+i,"武汉"+i,new Date()));
        }
        return  list;
    }

    /**
     * 根据ID查询一个用户
     */
    @ApiOperation(value ="根据ID查询用户" ,consumes = "根据ID查询用户")
    @GetMapping("queryUserById")
    public User queryAllUser(@RequestParam("userId")Integer id){  //加了RequestParam之后可以解决调试时验证问题
        return  new User(id,"小明","武汉",new Date());
    }

    /**
     * 添加一个用户
     */
    @ApiOperation(value ="添加用户")
    @PostMapping("addUser")
    public ResultObject addUser(@RequestBody User user){//@RequestBody验证前端所有数据非空的同时要求必须提交json格式的数据
        System.out.println(user);
        return  new ResultObject(200,"添加成功");
    }

    /**
     * 添加一个用户
     */
    @ApiOperation(value ="添加用户2")
    @ApiImplicitParams(value = {
            @ApiImplicitParam(name = "userId", value = "用户标识", required = true, paramType = "整数", dataType = "整数"),
            @ApiImplicitParam(name = "userName", value = "用户名称", required = true, paramType = "字符串", dataType = "字符串")
    })
    @PostMapping("addUser2")
    public ResultObject addUser2(User user){//@RequestBody验证前端所有数据非空的同时要求必须提交json格式的数据
        System.out.println(user);
        return  new ResultObject(200,"添加成功");
    }


    /**
     * 添加一个用户
     */
    @ApiOperation(value ="修改用户")
    @PostMapping("updateUser")
    public ResultObject updateUser(@RequestBody User user){//@RequestBody验证前端所有数据非空的同时要求必须提交json格式的数据
        System.out.println(user);
        return  new ResultObject(200,"修改成功");
    }

    /**
     * 根据ID删除一个用户
     */
    @ApiOperation(value ="删除用户")
    @DeleteMapping("deleteUser")
    public ResultObject deleteUser(@RequestParam("userId") Integer id){
        System.out.println(id);
        return  new ResultObject(200,"删除成功");
    }

}

启动工程，访问swagger-ui.html

http://localhost:8080/swagger-ui.html

控制器的文档说明：

模型层的文档：

 

Swagger皮肤更换：

<!-- swagger -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>
<!-- swagger-ui -->
<!--<dependency>-->
<!--    <groupId>io.springfox</groupId>-->
<!--    <artifactId>springfox-swagger-ui</artifactId>-->
<!--    <version>2.9.2</version>-->
<!--</dependency>-->

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>swagger-bootstrap-ui</artifactId>
    <version>1.9.6</version>
</dependency>

重启工程，访问地址：

http://localhost:8080/doc.html