Spring Boot 入门系列（二十二）使用Swagger2构建 RESTful API文档

前面介绍了如何Spring Boot 快速打造Restful API 接口，也介绍了如何优雅的实现 Api 版本控制，不清楚的能够看我以前的文章：https://www.cnblogs.com/zhangweizhong/category/1657780.html

在实际项目中，Api 接口系统对接过程当中，Api 接口文档是很是重要的文档。通常是设计完成以后，同时编写Api 接口文档，而后将接口文档发给相关人员，因而你们就按照该文档开发、集成并最终上线。可是，这是一种很是理想的状态，实际开发中，接口不断变化，接口文档也必须保持更新，这是一个很是麻烦的过程！为了解决这些问题，Swagger2 应运而生。接下来，就和大伙聊一聊 Spring Boot 如何整合Swagger2，使用Swagger2构建 RESTful API文档。

 

什么是Swagger

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。是世界上最流行的 API 表达工具 。咱们知道，RESTful API 可能要面对多个开发人员或多个开发团队：IOS开发、Android开发或是Web前端开发等。为了减小与其余团队平时开发期间的频繁沟通成本，通常咱们会建立一份API文档来记录全部接口细节，可是api 接口文档存在如下问题：

• 因为接口众多，而且细节复杂（须要考虑不一样的HTTP请求类型、HTTP头部信息、HTTP请求内容等），要建立这样一份高质量的文档自己就是件很是吃力的事。
• 随着需求的不断变化，接口文档也必须同步修改，这很容易致使文档和业务不一致状况出现。

为了解决这些问题，Swagger2 应运而生。它能够轻松的整合到Spring Boot 中，自动生成强大的 RESTful API文档。这样既能够减小咱们建立文档的工做量，同时说明内容又整合入实现代码中，让维护文档和修改代码整合为一体，可让咱们在修改代码逻辑的同时方便的修改文档说明。另外Swagger2也提供了完整的测试页面，来调试每一个API 接口。

下面就以SpringBoot中集成Swagger为例作介绍说明Swagger2 的功能和做用。

 

Spring Boot 实现Swagger 2

Spring Boot 集成 Swagger 2很简单，首先新建一个 SpringBoot 项目，这里就不从新建立项目，直接使用以前的rest 测试项目。而后引入依赖并作基础配置便可：

一、配置Swagger2的依赖

在pom.xml 配置文件中，增长Swagger 2 的相关依赖，具体以下：

<!-- swagger2 依赖配置-->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.8.0</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.8.0</version>
</dependency>

注意，swagger 2 的版本号和 spring boot的版本号有些不匹配，最开始用2.2的版本和spring boot 的版本还不匹配，后来把 swagger 2 换成了2.8。

 

二、建立Swagger 2配置类

在com.weiz.config 包中，增长Swagger 2 的配置类，SwaggerConfig 类，具体代码以下：

package com.weiz.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
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;

@Configuration
@EnableSwagger2
public class Swagger2Config implements WebMvcConfigurer {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.weiz.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Spring Boot中使用Swagger2构建RESTful APIs")
                .description("Spring Boot相关文章请关注：https://www.cnblogs.com/zhangweizhong")
                .termsOfServiceUrl("https://www.cnblogs.com/zhangweizhong")
                .contact("架构师精进")
                .version("1.0")
                .build();
    }

    /**
     *  swagger增长url映射
     * @param registry
     */
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("swagger-ui.html")
                .addResourceLocations("classpath:/META-INF/resources/");

        registry.addResourceHandler("/webjars/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/");
    }
}

说明：@Configuration 注解让Spring boot来加载该类配置，@EnableSwagger2注解启用Swagger 2，经过配置一个Docket Bean，配置映射路径和要扫描的接口的位置。apiInfo，主要配置一下Swagger2文档网站的信息，例如网站的title、网站的描述、使用的协议等等。

注意：

　　一、basePackage 能够在SwaggerConfig 里面配置 com.weiz.controller，也能够在启动器里面 ComponentScan 配置。

　　二、须要在swaggerconfig 中配置swagger 的url 映射。

 

 三、添加文档说明内容

上面配置完成以后，接下来须要在api 接口上增长内容说明。这里方便起见，就直接在以前的UserController 中，增长相应的接口内容说明，代码以下所示：

package com.weiz.controller;

import com.weiz.pojo.SysUser;
import com.weiz.service.UserService;
import com.weiz.utils.JSONResult;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.n3r.idworker.Sid;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.*;

@Api(tags = {"用户接口"})
@RestController
@RequestMapping("/")
public class UserController {

    @Autowired
    private UserService userService;

    @Autowired
    private Sid sid;

    @ApiOperation(value="建立用户", notes="根据User对象建立用户")
    @PostMapping(value = "user")
    public JSONResult create(@RequestBody SysUser user) throws Exception {
        String userId = sid.nextShort();
        user.setId(userId);
        userService.saveUser(user);
        return JSONResult.ok("保存成功");
    }

    @ApiOperation(value="更新用户详细信息", notes="根据id来指定更新对象，并根据传过来的user信息来更新用户详细信息")
    @PutMapping(value = "user")
    public JSONResult update(@RequestBody SysUser user) {
        userService.updateUser(user);
        return JSONResult.ok("保存成功");
    }

    @ApiOperation(value="删除用户", notes="根据url的id来指定删除对象")
    @DeleteMapping("user/{userId}")
    public JSONResult delete(@PathVariable String userId) {
        userService.deleteUser(userId);
        return JSONResult.ok("删除成功");
    }

    @ApiOperation(value="查询用户",notes = "经过用户ID获取用户信息")
    @GetMapping("user/{userId}")
    public JSONResult queryUserById(@PathVariable String userId) {
        return JSONResult.ok(userService.queryUserById(userId));
    }
}

说明：

　　一、@Api注解，用来给整个controller 增长说明。
　　二、@ApiOperation注解，用来给各个API 方法增长说明。
　　三、@ApiImplicitParams、@ApiImplicitParam注解，用来给参数增长说明。

　　四、Swagger 还有用于对象参数的注解，对象参数的描述也能够放在实体类中。这里不细说，你们能够自行研究。

 

测试验证

完成上面的配置和代码修改以后，Swagger 2 就集成到Spring boot 项目中了，接下来启动Spring Boot程序，访问：http://localhost:8088/swagger-ui.html 

 

最后

以上，就把Spring Boot 如何整合Swagger2，使用Swagger2构建 RESTful API文档 介绍完了。实现仍是比较简单的，可是仍是须要理解里面的相关注解的用法。

这个系列课程的完整源码，也会提供给你们。你们关注个人微信公众号（架构师精进），回复：springboot源码。获取这个系列课程的完整源码。