SpringBoot整合Swagger

前言

  随着互联网的发展，技术越来越成熟，网站架构从开始的前后端一起变成了前后端分离，这样前后端就得靠着 Api 文档

  联系，大量的接口文档编写以及修改会占用开发的时间，所以项目中往往会引入 Swagger 这类 Api 开发框架，更加方

  便的生成和管理 Api 文档，并且 Swagger 生成的 Api 文档还会随着接口更改而相应发生改变。

源码

  GitHub地址：https://github.com/intomylife/SpringBoot

环境

• JDK 1.8.0 +
• Maven 3.0 +
• MySQL 5.6.17
• SpringBoot 2.0.3

开发工具

• IntelliJ IDEA 

SQL脚本  

DROP TABLE IF EXISTS `springboot_swagger` ;
CREATE TABLE `springboot_swagger` (
  `id` bigint(20) unsigned NOT NULL AUTO_INCREMENT COMMENT '自增ID',
  `type` varchar(2) DEFAULT NULL COMMENT '生活用品类别：1. 家电类 2. 厨具',
	`name` varchar(50) DEFAULT NULL COMMENT '生活用品名称',
	`description` varchar(200) DEFAULT NULL COMMENT '生活用品描述',
  PRIMARY KEY (`id`) USING BTREE
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 ROW_FORMAT=COMPACT COMMENT='springboot整合swagger测试表';

INSERT INTO springboot_swagger ( type , name , description )
VALUES ('1','电饭煲','用来蒸饭'),('1','电热壶','用来烧水'),('1','空调','用来制冷或制热'),('2','菜刀','用来切菜'),('2','刨子','用来剥皮'),('2','打蛋器','用来搅拌鸡蛋');

正文

commons 工程 - 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 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <!-- 三坐标 -->
    <groupId>com.zwc</groupId>
    <artifactId>springboot-swagger-commons</artifactId>
    <version>0.0.1-SNAPSHOT</version>

    <!-- 工程名称和描述 -->
    <name>springboot-swagger-commons</name>
    <description>公用工程</description>

    <!-- 打包方式 -->
    <packaging>jar</packaging>

    <!-- 在properties下声明相应的版本信息，然后在dependency下引用的时候用${spring-version}就可以引入该版本jar包了 -->
    <properties>
        <!-- 编码 -->
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
        <!-- jdk -->
        <java.version>1.8</java.version>

        <!-- springboot -->
        <platform-bom.version>Cairo-SR3</platform-bom.version>

        <!-- ali 连接池 -->
        <druid.version>1.1.9</druid.version>
        <!-- ali json -->
        <fastjson.version>1.2.47</fastjson.version>
        <jackson.mapper.asl.version>1.9.9</jackson.mapper.asl.version>

        <!-- mybatis -->
        <mybatis-plus-boot-starter.version>3.0-RELEASE</mybatis-plus-boot-starter.version>
        <mybatis-spring-boot-starter.version>1.3.2</mybatis-spring-boot-starter.version>
        <mybatis.ehcache.version>1.1.0</mybatis.ehcache.version>

        <!-- swagger -->
        <!-- pringfox-swagger2依然是依赖OSA规范文档，也就是一个描述API的json文件 -->
        <!-- 而这个组件的功能就是帮助我们自动生成这个json文件 -->
        <!-- 我们会用到的另外一个组件springfox-swagger-ui就是将这个json文件解析出来 -->
        <!-- 用一种更友好的方式呈现出来 -->
        <springfox.version>2.7.0</springfox.version>
    </properties>

    <!-- 加入依赖 -->
    <dependencies>
        <!-- ali 连接池依赖 -->
        <dependency>
            <groupId>com.alibaba</groupId>
            <artifactId>druid-spring-boot-starter</artifactId>
            <version>${druid.version}</version>
        </dependency>

        <!-- mysql 依赖 -->
        <dependency>
            <groupId>mysql</groupId>
            <artifactId>mysql-connector-java</artifactId>
        </dependency>

        <!-- ali json依赖 -->
        <dependency>
            <groupId>com.alibaba</groupId>
            <artifactId>fastjson</artifactId>
            <version>${fastjson.version}</version>
        </dependency>
        <dependency>
            <groupId>org.codehaus.jackson</groupId>
            <artifactId>jackson-mapper-asl</artifactId>
            <version>${jackson.mapper.asl.version}</version>
        </dependency>

        <!-- mybatis 依赖 -->
        <dependency>
            <groupId>org.mybatis.spring.boot</groupId>
            <artifactId>mybatis-spring-boot-starter</artifactId>
            <version>${mybatis-spring-boot-starter.version}</version>
        </dependency>
        <dependency>
            <groupId>com.baomidou</groupId>
            <artifactId>mybatis-plus-boot-starter</artifactId>
            <version>${mybatis-plus-boot-starter.version}</version>
        </dependency>
        <dependency>
            <groupId>org.mybatis.caches</groupId>
            <artifactId>mybatis-ehcache</artifactId>
            <version>${mybatis.ehcache.version}</version>
        </dependency>

        <!-- swagger 依赖 -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>${springfox.version}</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>${springfox.version}</version>
        </dependency>
    </dependencies>

    <!-- 依赖 jar 包版本管理的管理器 -->
    <!-- 如果 dependencies 里的 dependency 自己没有声明 version 元素，那么 maven 就此处来找版本声明。 -->
    <!-- 如果有，就会继承它；如果没有就会报错，告诉你没有版本信息 -->
    <!-- 优先级：如果 dependencies 里的 dependency 已经声明了版本信息，就不会生效此处的版本信息了 -->
    <dependencyManagement>
        <dependencies>
            <!-- SpringBoot -->
            <dependency>
                <groupId>io.spring.platform</groupId>
                <artifactId>platform-bom</artifactId>
                <version>${platform-bom.version}</version>
                <type>pom</type>
                <scope>import</scope>
            </dependency>
        </dependencies>
    </dependencyManagement>

    <!-- 插件依赖 -->
    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
        </plugins>
    </build>

</project>

• 配置一些共用依赖，其中包括 springfox-swagger2 和 springfox-swagger-ui 来整合 Swagger

commons 工程 - system.properties

# mybatis-plus
## 扫描 mapper 文件
mybatis-plus.mapper-locations=classpath*:com/zwc/*/mapper/xml/*.xml
## 扫描实体类
mybatis-plus.type-aliases-package=com.zwc.*.domain

• 需要连接数据库，所以依旧配置了 MyBatis-Plus
• 一些共用配置，不经常修改的，或者是可以统一修改的
• 这里扫描 Mapper 文件和实体类都用了通配符的方式
• 比如还可以配置 OSS 的配置信息，Redis 的配置信息，MongoDB 的配置信息等等..

commons 工程 - 自定义配置 - MyBatisPlusConfig

package com.zwc.config;

import com.baomidou.mybatisplus.extension.plugins.PaginationInterceptor;
import com.baomidou.mybatisplus.extension.spring.MybatisSqlSessionFactoryBean;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.PropertySource;
import org.springframework.core.io.support.PathMatchingResourcePatternResolver;

/*
 * @ClassName MyBatisPlusConfig
 * @Desc TODO   mybatis-plus 配置
 * @Date 2019/4/3 14:31
 * @Version 1.0
 */
@Configuration
@PropertySource("classpath:system.properties")
public class MyBatisPlusConfig {

    /*
     * @ClassName MyBatisPlusConfig
     * @Desc TODO   mybatis-plus 配置拦截
     * @Date 2019/3/26 18:13
     * @Version 1.0
     */
    @Bean
    public PaginationInterceptor paginationInterceptor(){
        PaginationInterceptor paginationInterceptor = new PaginationInterceptor();
        // 设置方言
        paginationInterceptor.setDialectType("mysql");
        return paginationInterceptor;
    }

}

• 注意这里在注入类的时候，还要加载自定的配置文件，因为 SpringBoot 不会默认加载 system.properties
• 配置了 MyBatis-Plus 的分页插件，方言为 MySQL

commons 工程 - 自定义配置 - SwaggerConfig

package com.zwc.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.PropertySource;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 * @ClassName SwaggerConfig
 * @Desc TODO   swagger 配置
 * @Date 2019/4/3 10:33
 * @Version 1.0
 */
@Configuration
@EnableSwagger2
public class SwaggerConfig {

    /*
     * @ClassName SwaggerConfig
     * @Desc TODO   swagger 配置信息
     * @Date 2019/4/3 11:00
     * @Version 1.0
     */
    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())     // swagger 网页描述信息
                .enable(true)   // 是否开启
                .select()       // 选择那些路径和 api 会生成 document
                .apis(RequestHandlerSelectors.basePackage("com.zwc"))   // com.zwc 包下的 api 会生成 document
                .paths(PathSelectors.any()) // 表示所有路径都符合。PathSelectors.none() 表示所有路径都不符合
                .build();
    }

    /*
     * @ClassName SwaggerConfig
     * @Desc TODO   swagger 网页描述信息
     * @Date 2019/4/3 10:40
     * @Version 1.0
     */
    private ApiInfo apiInfo(){
        return new ApiInfoBuilder()
                .title("springboot 整合 swagger") // 标题
                .description("使用 springboot 整合 swagger 来构建 api 文档") // 描述
                .version("1.0.1")   // 版本
                .build();
    }

}

• @Configuration + @Bean 注解注入 Swagger 相关配置
• @EnableSwagger2 注解启动 Swagger
• @Bean -> docket：其中 .paths() 用来指定哪些路径需要生成 Api，开发时默认设置为 any() 表示全部，当你把项目部署到服务器上时，一般会把这里设置成 none()
• apiInfo()：用来配置页面显示的主体信息，如标题，描述以及版本号等等...

commons 工程 - 项目结构 

service 工程 

service 工程是一个父工程，里面可能会包含 基础模块，用户模块，订单模块等等... 每个模块中又会分为 core 和 api

service 工程 - base-service-core - application.properties

# 端口
server.port=8082

# 数据源
spring.datasource.driver-class-name=com.mysql.jdbc.Driver
spring.datasource.url=jdbc:mysql://127.0.0.1:3306/base_db?useUnicode=true&characterEncoding=utf8&zeroDateTimeBehavior=convertToNull&allowMultiQueries=true&serverTimezone=PRC&useSSL=false
spring.datasource.username=root
spring.datasource.password=123456

# 打印 sql 日志
logging.level.com.zwc.base.mapper=debug

• 配置了数据源，注意更换为你自己本地的连接信息

service 工程 - base-service-core - 实体类

package com.zwc.base.domain;

import com.baomidou.mybatisplus.annotation.IdType;
import com.baomidou.mybatisplus.annotation.TableId;
import com.baomidou.mybatisplus.extension.activerecord.Model;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;

import java.io.Serializable;

/*
 * @ClassName SpringBootSwagger
 * @Desc TODO   springboot 整合 swagger 测试表
 * @Date 2019/4/3 11:07
 * @Version 1.0
 */
@Data
@ApiModel("springboot 整合 swagger 测试表")
public class SpringbootSwagger extends Model<SpringbootSwagger> {

    private static final long serialVersionUID = -7876888313791106541L;


    /**
     * 自增ID
     */
    @ApiModelProperty(value = "主键")
    @TableId(value = "id", type = IdType.AUTO)
    private Long id;

    /**
     * 生活用品类别：1. 家电类 2. 厨具
     */
    @ApiModelProperty(value = "生活用品类别：1. 家电类 2. 厨具")
    private String type;

    /**
     * 生活用品名称
     */
    @ApiModelProperty(value = "生活用品名称")
    private String name;

    /**
     * 生活用品描述
     */
    @ApiModelProperty(value = "生活用品描述")
    private String description;

    public static final String ID = "id";

    public static final String TYPE = "type";

    public static final String NAME = "name";

    public static final String DESCRIPTION = "description";

    @Override
    protected Serializable pkVal() {
        return this.id;
    }
}

• @Data 注解：自动生成 getter 和 setter 方法
• @ApiModel 注解：表示此类会被 Swagger 识别，生成在 Api 文档
• @ApiModelProperty 注解：表示此字段会被 Swagger 识别，生成在 Api 文档中；此注解一般有两个参数：① value：此字段在 Api 文档中的描述信息 ② hidden：此字段是否显示

  注：还有相关的扩展实体类这里不一一展示占篇幅了，具体代码可以在 Github 中获取 

service 工程 - base-service-core - controller 前端控制器

package com.zwc.base.controller;

import com.baomidou.mybatisplus.extension.plugins.pagination.Page;
import com.zwc.base.dto.request.SpringbootSwaggerRequestAddDTO;
import com.zwc.base.dto.request.SpringbootSwaggerRequestDTO;
import com.zwc.base.dto.request.SpringbootSwaggerRequestQueryDTO;
import com.zwc.base.dto.response.SpringbootSwaggerResponseDTO;
import com.zwc.base.service.SpringbootSwaggerService;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.http.MediaType;
import org.springframework.web.bind.annotation.*;
import springfox.documentation.annotations.ApiIgnore;

/**
 * @ClassName SpringbootSwaggerController
 * @Desc TODO   springboot 整合 swagger 测试表 前端控制器
 * @Date 2019/4/3 13:48
 * @Version 1.0
 */
@RestController
@RequestMapping(value = "swagger") //  , produces = MediaType.APPLICATION_JSON_VALUE
@Api(value = "springboot 整合 swagger 测试表 前端控制器" , description = "springboot 整合 swagger 测试表 api")
// 此注解用在类上整个类都不会出现在 swagger 里；用在此类方法上，此类该方法不会出现在 swagger 里，其他方法依旧会出现在 swagger 里
// @ApiIgnore
public class SpringbootSwaggerController {

    @Autowired
    private SpringbootSwaggerService springbootSwaggerService;

    /*
     * @ClassName SpringbootSwaggerController
     * @Desc TODO   新增信息
     * @Date 2019/4/3 14:38
     * @Version 1.0
     */
    @RequestMapping(value = "/add" , method = RequestMethod.POST)
    @ApiOperation(value = "新增信息")
    public String add(SpringbootSwaggerRequestAddDTO springbootSwaggerRequestAddDTO){
        return springbootSwaggerService.add(springbootSwaggerRequestAddDTO);
    }

    /*
     * @ClassName SpringbootSwaggerController
     * @Desc TODO   根据 id 删除信息 ， 使用 @ApiParam 注解添加字段的描述，参数是否必填以 @ApiParam 注解中的 required 值为准
     * @Date 2019/4/3 14:56
     * @Version 1.0
     */
    @RequestMapping(value = "/delete/{id}" , method = RequestMethod.GET)
    @ApiOperation(value = "根据 id 删除信息")
    public String delete(@ApiParam(value = "主键 id" , required = true) @PathVariable(value = "id" , required = true) long id){
        return springbootSwaggerService.delete(id);
    }

    /*
     * @ClassName SpringbootSwaggerController
     * @Desc TODO   更新信息
     * @Date 2019/4/3 15:03
     * @Version 1.0
     */
    @RequestMapping(value = "/update" , method = RequestMethod.POST)
    @ApiOperation(value = "更新信息")
    public String update(SpringbootSwaggerRequestDTO springbootSwaggerRequestDTO){
        return springbootSwaggerService.update(springbootSwaggerRequestDTO);
    }

    /*
     * @ClassName SpringbootSwaggerController
     * @Desc TODO   分页查询信息
     * @Date 2019/4/3 14:02
     * @Version 1.0
     */
    @RequestMapping(value = "/pageUser" , method = RequestMethod.POST)
    @ApiOperation(value = "分页查询信息")
    public Page<SpringbootSwaggerResponseDTO> pageUser(SpringbootSwaggerRequestQueryDTO springbootSwaggerRequestQueryDTO){
        return springbootSwaggerService.getDataByPage(springbootSwaggerRequestQueryDTO);
    }

}

• @Api 注解：用来描述类，通常用在前端控制器中；每一个类中的接口会根据此注解划分归类
• @ApiIgnore 注解：此注解用在类上整个类都不会出现在 Swagger 里；用在此类方法上，此类该方法不会出现在 Swagger 里，其他方法依旧会出现在 Swagger 里
• @ApiOperation 注解：此接口在 Swagger 中的描述信息

启用项目，调用接口 

1. 端口8082（具体可以根据自己的喜好，在 application.properties 配置文件中配置 server.port） 
2. 查看 Api 文档接口：http://localhost:8082/swagger-ui.html

service 工程 - 项目结构

• 在 service 总工程中创建了一个 base-service 的基础模块
• 每一个模块中都包含 api 和 core

 

• api：主要包含接口，常量以及实体类的扩展类

• core：带有启动类的工程，此模块的核心代码都在里面

把多工程项目使用 IntelliJ IDEA  打开

1. 把项目从 GitHub 中下载到你的本地
2. 打开 IntelliJ IDEA 
3. 点击 File -> Open
4. 打开你下载到本地的项目目录
5. springboot-swagger -> springboot-swagger-service（选择打开此工程）
6. 打开 service 工程后
7. 再次点击 File -> Project Structrue
8. 选择 Modules，点击 '+' 符号
9. 点击 Import  Module
10. 还是打开你下载到本地的项目目录
11. springboot-swagger -> springboot-swagger-commons -> pom.xml
12. 点击 OK
13. 点击 Next，Finish
14. 点击 Apply，OK

---

结语

  到此 SpringBoot 整合 Swagger 就结束了，注意注解的使用，多多尝试，一定会成功的！

 

希望能够帮助到你

over