【SpringBoot】整合Swagger2 接口文档

前言

可能运用的开发模式：

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;



@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;



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

集成Swagger2的坐标：

        
        
            io.springfox
            springfox-swagger2
            2.9.2
        
        
        
            io.springfox
            springfox-swagger-ui
            2.9.2

创建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;


@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;



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

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

    
    @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,"修改成功");
    }

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

}

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

【注意】启动的时候，有可能报空指针异常，解决办法参考：

确定了swagger2配置文件和依赖版本没有问题后，本来也以为是配置文件的bean没有被注入，但又在启动类上加了@ComponentScan()注解依然没用。翻阅资料，将springboot的2.6.7版本改为了2.0.7.RELEASE 后就解决了，可能是springboot版本过高和swagger2的版本不匹配造成的。

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

控制器的文档说明：

模型层的文档：

Swagger皮肤更换：



    io.springfox
    springfox-swagger2
    2.9.2







新皮肤依赖

    com.github.xiaoymin
    swagger-bootstrap-ui
    1.9.6

重启工程，访问地址：

http://localhost:8080/doc.html

分类: 【SpringBoot】

【SpringBoot】整合Swagger2 接口文档

Java相关栏目本月热门文章