Spring boot 多模块项目 + Swagger 让你的API可视化

Spring boot 多模块项目 + Swagger 让你的API可视化

前言

手写 Api 文档的几个痛点：

• 文档需要更新的时候，需要再次发送一份给前端，也就是文档更新交流不及时。
• 接口返回结果不明确
• 不能直接在线测试接口，通常需要使用工具，比如postman
• 接口文档太多，不好管理

为了前后台更好的对接，为了以后交接方便，为了不再长篇大论的手写 api 文档，那么就来用Swagger吧(不是打广告，确实强)，它可以轻松的整合到 Spring 中，它既可以减少我们手写 api 文档的时间，同时又将说明文档整合到我们的代码中，这样前台看着也方便,后台工作也舒坦。

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。Swagger 让部署管理和使用功能强大的API从未如此简单(其他好处网上自己搜在这里就不再多说了)。

官网地址： https://swagger.io/

本篇内容：

（1）构建多模块项目（可选单模块步骤）
（2）pom.xml 配置加载依赖
（3）Swagger 配置类（Bean）
（4）启动类配置
（5）创建工具类
（6）User 实例类
（7）定义 restful 接口（Controller 层）

为帮助快速入门上手使用，提供了简单的增删改查，使用的参数配置示例

本篇测试环境：

• SpringBoot 2.0.5.RELEASE
• Swagger 2.9.2
• JDK 1.8.191

成功截图：

第一步：构建多模块项目（可选步骤）

如果想使用多模块，请先构建项目（建议）：

• Spring Boot 多模块结构项目构建与测试（详细图文教程）IDEA 版

如果不想使用多模块（下面模块请根据自己项目修改）

• Spring Boot 创建项目（IDEA 版）

所有涉及到的文件结构：

第二步：pom.xml 配置加载依赖

Spring boot 项目都会有一些依赖，为了更直观，只贴必要的部分
为你的 Spring Boot 项目再增加下面两个依赖：
pom.xml 配置：

<!--可以去下面地址查看最近版本-->
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
<dependency>
  <groupId>io.springfox</groupId>
  <artifactId>springfox-swagger2</artifactId>
  <version>2.9.2</version>
</dependency>

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
<dependency>
  <groupId>io.springfox</groupId>
  <artifactId>springfox-swagger-ui</artifactId>
  <version>2.9.2</version>
</dependency>

第三步：Swagger 配置类（Bean）

注意：

• basePackage 是需要自己配置的，换成自己需要扫描的包，会扫描其所有子包
• 一个就配主模块，多个就配大包，或分开配

用 @Configuration 注解该类，等价于XML中配置beans；
用 @Bean 标注方法等价于XML中配置bean
不是不可以使用 xml，提倡使用注解，是不是想起点什么？

SwaggerConfig.java 源代码：

package com.xpwi.main.config;

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.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;

/**
 * 描述：Swagger2 Config Bean
 *
 * @author Xiao Pengwei
 * @since 2019-03-27
 */
@Configuration
public class SwaggerConfig {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.xpwi"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("SpringBoot使用Swagger构建api文档")
                .description("简单优雅的 restfun 风格 https://icode.blog.csdn.net")
                .termsOfServiceUrl("https://icode.blog.csdn.net")
                .version("1.0")
                .build();
    }
}

第四步：启动类配置

Application.class 加上注解 @EnableSwagger2 表示开启Swagger

package com.xpwi.main;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.context.annotation.ComponentScan;
import org.springframework.web.bind.annotation.RestController;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

import java.util.Date;

/**
 * 描述：Spring Boot 多模块测试项目
 * @author Xiao Pengwei
 * @since  2019-03-25
 */

@EnableSwagger2
@SpringBootApplication
@RestController
//扫描 main,test 模块中的下的所有包
//在 pom 加载子模块依赖才可以扫包
@ComponentScan({"com.xpwi.main","com.xpwi.test","com.xpwi.login"})
public class App {

    public static void main(String[] args) {
        //启动 Web 容器
        SpringApplication.run(App.class, args);
        System.out.println("[启动成功]"+new Date());
    }
}

第五步：创建工具类

用于返回通用数据格式的工具类
CommonResult.java 源代码：

package com.xpwi.main.util;

/**
 * 描述：通用返回类型
 * @author Xiao Pengwei
 * @since  2019-03-27
 */
public class CommonResult {

    private String status;

    private Object result;

    private Object message;

    public String getStatus() {
        return status;
    }

    public void setStatus(String status) {
        this.status = status;
    }

    public Object getResult() {
        return result;
    }

    public void setResult(Object result) {
        this.result = result;
    }

    public Object getMessage() {
        return message;
    }

    public void setMessage(Object message) {
        this.message = message;
    }
}

第六步：User 实例类

User 模拟对应数据库字段的实体类
User.java 源代码：

package com.xpwi.main.entity;

import java.util.Date;

/**
 * 描述：User 实体类
 * @author Xiao Pengwei
 * @since  2019-03-27
 */
public class User {
    private String id;
    private String username;
    private int age;
    private Date ctm;

    public String getId() {
        return id;
    }

    public void setId(String id) {
        this.id = id;
    }

    public String getUsername() {
        return username;
    }

    public void setUsername(String username) {
        this.username = username;
    }

    public int getAge() {
        return age;
    }

    public void setAge(int age) {
        this.age = age;
    }

    public Date getCtm() {
        return ctm;
    }

    public void setCtm(Date ctm) {
        this.ctm = ctm;
    }
}

第七步：！定义 restful 接口（Controller 层）

最重要的一步，也是开发中最常用的一步
创建 UserController.java 源代码：

package com.xpwi.main.controller;

import com.xpwi.main.entity.User;
import com.xpwi.main.util.CommonResult;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RestController;
import springfox.documentation.annotations.ApiIgnore;

import java.util.ArrayList;
import java.util.Collections;
import java.util.HashMap;
import java.util.List;
import java.util.Map;

/**
 * 描述：Controller 类
 * @author Xiao Pengwei
 * @since  2019-03-27
 */
@RestController
@Api(value = "用户测试模块")
public class UserController {

    // 创建线程安全的Map
    static Map<String, User> users = Collections.synchronizedMap(new HashMap<String, User>());

    /**
     * 根据ID查询用户
     * @param id
     * @return
     */
    @ApiOperation(value="获取用户详细信息", notes="根据url的id来获取用户详细信息")
    @ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "String", paramType = "path")
    @RequestMapping(value = "user/{id}", method = RequestMethod.GET)
    public ResponseEntity<CommonResult> getUserById (@PathVariable(value = "id") String id){
        CommonResult commonResult = new CommonResult();
        try {
            User user = users.get(id);
            commonResult.setResult(user);
            commonResult.setStatus("ok");
        } catch (Exception e) {
            commonResult.setResult(e.getClass().getName() + ":" + e.getMessage());
            commonResult.setStatus("error");
            e.printStackTrace();
        }
        return ResponseEntity.ok(commonResult);
    }

    /**
     * 查询用户列表
     * @return
     */
    @ApiOperation(value="获取用户列表", notes="获取用户列表")
    @RequestMapping(value = "users", method = RequestMethod.GET)
    public ResponseEntity<CommonResult> getUserList (){
        CommonResult commonResult = new CommonResult();
        try {
            List<User> userList = new ArrayList<User>(users.values());
            commonResult.setResult(userList);
            commonResult.setStatus("ok");
        } catch (Exception e) {
            commonResult.setResult(e.getClass().getName() + ":" + e.getMessage());
            commonResult.setStatus("error");
            e.printStackTrace();
        }
        return ResponseEntity.ok(commonResult);
    }

    /**
     * 添加用户
     * @param user
     * @return
     */
    @ApiOperation(value="创建用户", notes="根据User对象创建用户")
    @ApiImplicitParam(name = "user", value = "用户详细实体user", required = true, dataType = "User")
    @RequestMapping(value = "user", method = RequestMethod.POST)
    public ResponseEntity<CommonResult> add (@RequestBody User user){
        CommonResult commonResult = new CommonResult();
        try {
            users.put(user.getId(), user);
            commonResult.setResult(user.getId());
            commonResult.setStatus("ok");
        } catch (Exception e) {
            commonResult.setResult(e.getClass().getName() + ":" + e.getMessage());
            commonResult.setStatus("error");

            e.printStackTrace();
        }
        return ResponseEntity.ok(commonResult);
    }

    /**
     * 根据id删除用户
     * @param id
     * @return
     */
    @ApiOperation(value="删除用户", notes="根据url的id来指定删除用户")
    @ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "String", paramType = "path")
    @RequestMapping(value = "user/{id}", method = RequestMethod.DELETE)
    public ResponseEntity<CommonResult> delete (@PathVariable(value = "id") String id){
        CommonResult commonResult = new CommonResult();
        try {
            users.remove(id);
            commonResult.setResult(id);
            commonResult.setStatus("ok");
        } catch (Exception e) {
            commonResult.setResult(e.getClass().getName() + ":" + e.getMessage());
            commonResult.setStatus("error");

            e.printStackTrace();
        }
        return ResponseEntity.ok(commonResult);
    }

    /**
     * 根据id修改用户信息
     * @param user
     * @return
     */
    @ApiOperation(value="更新信息", notes="根据url的id来指定更新用户信息")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "String",paramType = "path"),
            @ApiImplicitParam(name = "user", value = "用户实体user", required = true, dataType = "User")
    })
    @RequestMapping(value = "user/{id}", method = RequestMethod.PUT)
    public ResponseEntity<CommonResult> update (@PathVariable("id") String id, @RequestBody User user){
        CommonResult commonResult = new CommonResult();
        try {
            User user1 = users.get(id);
            user1.setUsername(user.getUsername());
            user1.setAge(user.getAge());
            users.put(id, user1);
            commonResult.setResult(user1);
            commonResult.setStatus("ok");
        } catch (Exception e) {
            commonResult.setResult(e.getClass().getName() + ":" + e.getMessage());
            commonResult.setStatus("error");

            e.printStackTrace();
        }
        return ResponseEntity.ok(commonResult);
    }

    @ApiIgnore//使用该注解忽略这个API
    @RequestMapping(value = "/hi", method = RequestMethod.GET)
    public String  jsonTest() {
        return " hi you!";
    }
}

第八步：启动 Spring Boot，打开浏览器

只需访问：

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

swagger-ui.html 是默认的，不用担心自己没有创建这个文件，这个就是那个 UI 咯

第九步：常用注解

swagger 提供的常用的注解有：

• @Api：用在类上，说明该类的作用
• @ApiOperation：用在方法上，说明方法的作用，标注在具体请求上，value 和 notes 的作用差不多，都是对请求进行说明；tags 则是对请求进行分类的，比如你有好几个 controller，分别属于不同的功能模块，那这里我们就可以使用 tags 来区分了。
• @ApiImplicitParams：用在方法上包含一组参数说明
• @ApiImplicitParam：用在 @ApiImplicitParams 注解中，指定一个请求参数的各个方面。
• @ApiResponses：用于表示一组响应
• @ApiResponse：用在 @ApiResponses 中，一般用于表达一个错误的响应信息
• @ApiModel：描述一个 Model 的信息（这种一般用在post创建的时候，使用
  @RequestBody 这样的场景，请求参数无法使用 @ApiImplicitParam 注解进行描述的时候）表明这是一个被 swagger 框架管理的 model，用于class上
• @ApiModelProperty： 这里顾名思义，描述一个 model 的属性，就是标注在被标注了 @ApiModel 的class的属性上，这里的 value 是对字段的描述，example 是取值例子，注意这里的 example很有用，对于前后端开发工程师理解文档起到了关键的作用，因为会在 api 文档页面上显示出这些取值来；这个注解还有一些字段取值，可以自己研究，举例说一个：position，表明字段在 model 中的顺序。

第十步：使用

一般 swagger 需要一下api的权限，需要在对应的模块进行排除：
http://localhost:8080/swagger-resources/configuration/ui
http://localhost:8080/swagger-resources
http://localhost:8080/api-docs
http://localhost:8080/swagger-ui.html
http://localhost:8080/swagger-resources/configuration/security

如果项目上线并且需要关闭 swagger 接口，可以通过配置权限，或者再 SwaggerConfig 里面
return new Docket 的时候加多一个.enable(false)

技术朋友群

• 一键加群
• QQ群：621657432