Spring Boot整合swagger2

• 前言：

由于最近维护的项目增加了新的功能模块，本人维护的项目较为古老，jdk使用的都是1.6的；和最新的jdk14来说，差的不是一星半点；在后端接口开发完成后，往往还要再前端进行接口文档的书写，而且需求的变更导致后端接口的变化，还要再进行前端接口文档的维护，确实是相当的麻烦。由于以前接触过一点swagger的使用，隧建立了一个spring boot项目用来整合swagger，以提升自己的认识。

• 新建spring boot项目，这里使用了Lombok插件以及spring-data-jpa，数据库使用的是MySQL8，目录结构如下

• 引入swagger2的jar包，在pom.xml中添加如下依赖，这里版本使用的是

<properties>
    <java.version>1.8</java.version>
    <swagger.version>2.9.2</swagger.version>
</properties>
<!-- swagger-ui -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>${swagger.version}</version>
</dependency>
<!-- swagger2 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>${swagger.version}</version>
</dependency>

• 配置swagger

package com.yunxi.map.config;

import io.swagger.annotations.Api;
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;

/**
 * TODO swagger配置类
 *
 * @author xiaoshuaishuai
 * @date 2020-04-28 13:13
 */
@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.withClassAnnotation(Api.class))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        Contact contact = new Contact("肖**", "157********", "******@163.com");
        return new ApiInfoBuilder()
                .title("一丛小溪地图项目接口")
                .description("个人项目")
                .contact(contact)
                .version("1.0.0")
                .build();
    }
}

• 实体类配置（这里我的示例使用了这些类作为参数，个人觉得这样比较方便，也便于后期增加字段）

package com.yunxi.map.domain;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;
import org.springframework.data.annotation.CreatedBy;
import org.springframework.data.annotation.CreatedDate;
import org.springframework.data.annotation.LastModifiedBy;
import org.springframework.data.annotation.LastModifiedDate;
import org.springframework.data.jpa.domain.support.AuditingEntityListener;

import javax.persistence.*;
import java.io.Serializable;
import java.util.Date;

/**
 * TODO 用户表
 *
 * @author xiaoshuaishuai
 * @date 2020-04-24 19:51
 */
@Data
@Entity
@ApiModel(value = "User对象", description = "用户表")
public class User implements Serializable {

    private static final long serialVersionUID = 41651381570588628L;

    @ApiModelProperty(value = "主键id", example = "1")
    @Id
    @Column(unique = true, nullable = false)
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    @ApiModelProperty(value = "用户名")
    @Column
    private String username;

    @ApiModelProperty(value = "密码")
    @Column
    private String password;

    @ApiModelProperty(value = "手机号码")
    @Column
    private String telephone;

    @ApiModelProperty(value = "邮箱地址")
    @Column
    private String eMail;

    @ApiModelProperty(value = "地址")
    @Column
    private String address;

    @ApiModelProperty(value = "用户头像url地址")
    @Column
    private String headSculptureUrl;

    @ApiModelProperty(value = "所属行政区划名称")
    @Column
    private String regionName;

    @ApiModelProperty(value = "所属行政区划代码")
    @Column
    private String regionCode;

    @ApiModelProperty(value = "创建时间")
    @Column
    private Date createTime;

    @ApiModelProperty(value = "创建人")
    @Column
    private String creator;

    @ApiModelProperty(value = "最近一次的修改时间")
    @Column
    private Date updateTime;

    @ApiModelProperty(value = "最近一次的修改人")
    @Column
    private String modifier;

    @ApiModelProperty(value = "备注")
    @Column
    private String remark;

}

package com.yunxi.map.dto;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;

import java.io.Serializable;

/**
 * TODO 用户数据传输类
 *
 * @author xiaoshuaishuai
 * @date 2020-04-30 9:52
 */
@Data
@ApiModel(value = "用户数据传输对象", description = "用户数据传输类")
public class UserDto implements Serializable {

    private static final long serialVersionUID = 7836123583196690829L;

    @ApiModelProperty(value = "用户名")
    private String username;

    @ApiModelProperty(value = "密码")
    private String password;

    @ApiModelProperty(value = "邮箱", name = "eMail")
    private String eMail;

    @ApiModelProperty(value = "所属行政区划名称")
    private String regionName;

    @ApiModelProperty(value = "所属行政区划代码", hidden = true)
    private String regionCode;

}

• 接口配置 

package com.yunxi.map.controller;

import com.yunxi.map.domain.User;
import com.yunxi.map.dto.UserDto;
import com.yunxi.map.service.UserService;
import com.yunxi.map.vo.UserVo;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RestController;

import javax.annotation.Resource;

/**
 * TODO 用户controller
 *
 * @author xiaoshuaishuai
 * @date 2020-04-30 9:48
 */
@Api(tags = {"用户接口"})
@RestController
@RequestMapping(value = "/user")
public class UserController {

    @Resource
    private UserService userService;

    @ApiOperation(value = "新增用户接口", notes = "参数采用表单提交")
    @RequestMapping(value = "/add", method = RequestMethod.POST)
    public void addUser(UserDto userDto) {
        try {
            userService.addUser(userDto);
        } catch (Exception e) {
            e.printStackTrace();
        }
    }

    @ApiOperation(value = "用户详情接口")
    @RequestMapping(value = "/get", method = RequestMethod.GET)
    public UserVo getUser() {
        return null;
    }

}

这里我的配置文件如下，我使用的是yml格式，properties文件可以改成自己对应的格式

server:
  port: 80
spring:
  datasource:
    url: jdbc:mysql://localhost:3306/map?characterEncoding=utf-8&serverTimezone=Asia/Shanghai
    username: root
    password: root
  jpa:
    database: mysql
    database-platform: org.hibernate.dialect.MySQL8Dialect
    show-sql: true
    open-in-view: false # spring boot 默认开启视图，一般用不到，这里置为false
    hibernate:
      ddl-auto: update # 每次重启项目时，自动更新表结构

启动项目，在浏览器地址栏输入如下地址：http://localhost/swagger-ui.html

上图就是我比较疑惑的地方了，如果有人知道如何解决，请留言指教；这里虽然名称不一样，但是最终传参是正确的，也就是说不影响你的使用