Spring Boot整合Swagger2构建API文档

一、为什么需要使用Swagger？

当下很多公司都采取前后端分离的开发模式，前端和后端的工作由不同的工程师完成。在这种开发模式下，维持一份及时更新且完整的 Rest API 文档将会极大的提高我们的工作效率。传统意义上的文档都是后端开发人员手动编写的，相信大家也都知道这种方式很难保证文档的及时性，这种文档久而久之也就会失去其参考意义，反而还会加大我们的沟通成本。而 Swagger 给我们提供了一个全新的维护 API 文档的方式，下面我们就来了解一下它的优点：

• 代码变，文档变。只需要少量的注解，Swagger 就可以根据代码自动生成 API 文档，很好的保证了文档的时效性。
• 跨语言性，支持 40 多种语言。
• Swagger UI 呈现出来的是一份可交互式的 API 文档，我们可以直接在文档页面尝试 API 的调用，省去了准备复杂的调用参数的过程。
• 还可以将文档规范导入相关的工具（例如 SoapUI）, 这些工具将会为我们自动地创建自动化测试。

二、Spring Boot整合Swagger2

1、导入Swagger2依赖

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.6.1</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.6.1</version>
</dependency>

2、编写Swagger2配置类

@Configuration
@EnableSwagger2
public class Swagger2Configuration {
    @Bean
    public Docket buildDocket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(buildApiInfo())
                .select()
                // 要扫描的API(Controller)基础包
                .apis(RequestHandlerSelectors.basePackage("com.yiidian"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo buildApiInfo() {
        Contact contact = new Contact("一点教程网","","");
        return new ApiInfoBuilder()
                .title("一点教程网-SpringBoot整合Swagger2构建API文档")
                .description("文章管理服务api")
                .termsOfServiceUrl("http://www.yiidian.com")
                .contact(contact)
                .version("1.0.0").build();
    }
}

• @EnableSwagger2 注解表示开启SwaggerAPI文档相关的功能
• 在apiInfo方法中配置接口文档的title(标题)、描述、termsOfServiceUrl（服务协议）、版本等相关信息
• 在createRestApi方法中，basePackage表示扫描哪个package下面的Controller类作为API接口文档内容范围
• 在createRestApi方法中，paths表示哪一个请求路径下控制器映射方法，作为API接口文档内容范围

这时启动项目会发生以下错误：

org.springframework.context.ApplicationContextException: Failed to start bean 'documentationPluginsBootstrapper'; nested exception is java.lang.NullPointerException
	at org.springframework.context.support.DefaultLifecycleProcessor.doStart(DefaultLifecycleProcessor.java:181) ~[spring-context-5.3.18.jar:5.3.18]
	at org.springframework.context.support.DefaultLifecycleProcessor.access$200(DefaultLifecycleProcessor.java:54) ~[spring-context-5.3.18.jar:5.3.18]
	at org.springframework.context.support.DefaultLifecycleProcessor$LifecycleGroup.start(DefaultLifecycleProcessor.java:356) ~[spring-context-5.3.18.jar:5.3.18]
	at org.springframework.context.support.DefaultLifecycleProcessor$$Lambda$615/1559929085.accept(Unknown Source) ~[na:na]
	at java.lang.Iterable.forEach(Iterable.java:75) ~[na:1.8.0_31]

原因是SpringBoot的版本与Swagger2的版本不兼容导致。可以适当下调SpringBoot的版本，比如我这里把2.6.6版本降到2.5.6

<parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>2.6.6</version>
    <relativePath/> <!-- lookup parent from repository -->
</parent>

修改后启动就没问题了！做一下访问验证：http://localhost:8888/swagger-ui.html ，如下：

swagger不仅提供了静态的接口文档的展示，还提供了执行接口方法测试的功能。在下图中填入接口对应的参数，点击“try it out"就可以实现接口请求的发送与响应结果的展示。

三、Swagger2的常见注解

通常情况下Controller类及方法书写了swagger注解，就不需要写java注释了。写法如下：

  @ApiOperation(value = "添加文章", notes = "添加新的文章", tags = "Article",httpMethod = "POST")
  @ApiImplicitParams({
          @ApiImplicitParam(name = "title", value = "文章标题", required = true, dataType = "String"),
          @ApiImplicitParam(name = "content", value = "文章内容", required = true, dataType = "String"),
          @ApiImplicitParam(name = "categoryName", value = "文章类别", required = true, dataType = "String")
  })
  @ApiResponses({
          @ApiResponse(code=200,message="成功",response=ResponseResult.class),
  })
  @PostMapping("/article")
  public @ResponseBody  ResponseResult saveArticle2(
          @RequestParam(value="title") String title,  //参数1
          @RequestParam(value="content") String content,//参数2
          @RequestParam(value="categoryName") String categoryName//参数3
  ) {
    log.info("添加文章");
    return ResponseResult.success();
  }

swagger注释添加完成之后，接口文档变成如下的样子：

ApiModel注解的用法：

@Data
@ApiModel(value = "通用响应数据结构类")
public class ResponseResult {
  @ApiModelProperty(value="请求是否处理成功")
  private boolean isok;  //请求是否处理成功
  @ApiModelProperty(value="请求响应状态码",example="200、400、500")
  private int code; //请求响应状态码（200、400、500）
  @ApiModelProperty(value="请求结果描述信息")
  private String message;  //请求结果描述信息
  @ApiModelProperty(value="请求结果数据")
  private Object data; //请求结果数据（通常用于查询操作）

  .....
}

文档显示效果如下：

四、生产环境禁用Swagger2

我们的文档通常是在团队内部观看及使用的，不希望发布到生产环境让用户看到。

• 禁用方法1：使用注解@Profile({"dev","test"}) 表示在开发或测试环境开启，而在生产关闭。了解更多profile的内容：http://www.yiidian.com/course/backend_course/spring_boot/432421.html
• 禁用方法2：使用注解@ConditionalOnProperty(name = "swagger.enable", havingValue = "true") 然后在测试配置或者开发配置中 添加 swagger.enable = true 即可开启，生产环境不填则默认关闭Swagger.

更多使用细节可以参考：
https://www.ibm.com/developerworks/cn/java/j-using-swagger-in-a-spring-boot-project/index.html

 

下载本文源码：springboot-demo