SpringBoot集成Swagger3 —— 教你如何优雅的写文档

Swagger介绍及使用

导语：

相信无论是前端还是后端开发，都或多或少地被接口文档折磨过。前端经常抱怨后端给的接口文档与实际情况不一致。后端又觉得编写及维护接口文档会耗费不少精力，经常来不及更新。其实无论是前端调用后端，还是后端调用后端，都期望有一个好的接口文档。但是这个接口文档对于程序员来说，就跟注释一样，经常会抱怨别人写的代码没有写注释，然而自己写起代码起来，最讨厌的，也是写注释。所以仅仅只通过强制来规范大家是不够的，随着时间推移，版本迭代，接口文档往往很容易就跟不上代码了。

Swagger简介

• Swagger是一个开源的软件框架，可以帮助开发人员设计、构建和使用Web服务，将代码与文档结合在一起，完美的解决了上述问题，使开发人员将大部分精力集中到业务中，而不是文档的撰写。

官网：https://swagger.io

Swagger解决的痛点

传统方式提供文档有以下痛点：

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

Swagger也就是为了解决这个问题，当然也不能说Swagger就一定是完美的，当然也有缺点，最明显的就是代码移入性比较强。

Swagger3的改变

Swagger3.0的改动，官方文档总结如下几点：

1. 删除了对springfox-swagger2的依赖；
2. 删除所有@EnableSwagger2…注解；
3. 添加了springfox-boot-starter依赖项；
4. 移除了guava等第三方依赖；
5. 文档访问地址改为http://ip:port/project/swagger-ui/index.html。

SpringBoot集成Swagger3

• SpringBoot集成Swagger3与SpringBoot集成其他框架的套路基本一致，通常包括：加入依赖、编写application.properties、创建配置类和使用。

项目结构如下：

1. 加入依赖

在SpringBoot项目的pom.xml中引入Swagger3依赖：

pom.xml

 <dependency> <groupId>org.springframework.plugin 
     groupId> <artifactId>spring-plugin-core 
      artifactId> <version>2.0.0.RELEASE 
       version>  
        dependency> <dependency> <groupId>org.springframework.plugin 
         groupId> <artifactId>spring-plugin-metadata 
          artifactId> <version>2.0.0.RELEASE 
           version>  
            dependency> <dependency> <groupId>io.springfox 
             groupId> <artifactId>springfox-boot-starter 
              artifactId> <version>3.0.0 
               version> <exclusions> <exclusion> <groupId>org.springframework.plugin 
                groupId> <artifactId>spring-plugin-core 
                 artifactId>  
                  exclusion> <exclusion> <groupId>org.springframework.plugin 
                   groupId> <artifactId>spring-plugin-metadata 
                    artifactId>  
                     exclusion>  
                      exclusions>  
                       dependency>  
                        project> 

2. 编写application.properties文件

通常情况下swagger只能在开发环境或测试环境下开启，生产环境下需要进行关闭的。而swagger的开启与关闭可在application.properties中进行配置：

# 生产环境需设置为false springfox.documentation.swagger-ui.enabled=true 

3.创建配置类

通过@EnableOpenApi注解启动用Swagger的使用，同时在配置类中对Swagger的通用参数进行配置。

package cn.itcast.swagger.config; import com.github.xiaoymin.knife4j.spring.annotations.EnableKnife4j; import io.swagger.v3.oas.annotations.Operation; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import org.springframework.http.HttpMethod; import springfox.documentation.builders.*; import springfox.documentation.oas.annotations.EnableOpenApi; import springfox.documentation.schema.ScalarType; import springfox.documentation.service.*; import springfox.documentation.spi.DocumentationType; import springfox.documentation.spring.web.plugins.Docket; import java.util.ArrayList; import java.util.List; @Configuration @EnableOpenApi //注解启动用Swagger的使用，同时在配置类中对Swagger的通用参数进行配置 public class Swagger3Config { 
    @Bean public Docket createRestApi(){ 
    //返回文档概要信息 return new Docket(DocumentationType.OAS_30) .apiInfo(apiInfo()) .select() .apis(RequestHandlerSelectors.withMethodAnnotation(Operation.class)) .paths(PathSelectors.any()) .build() .globalRequestParameters(getGlobalRequestParameters()) .globalResponses(HttpMethod.GET,getGlobalResponseMessage()) .globalResponses(HttpMethod.POST,getGlobalResponseMessage()); } /* 生成接口信息，包括标题，联系人等 */ private ApiInfo apiInfo() { 
    return new ApiInfoBuilder() .title("Swagger3接口文档") .description("如有疑问,可联系百度") .contact(new Contact("李白","http://www.baidu.com","")) .version("1.0") .build(); } /* 封装全局通用参数 */ private List<RequestParameter> getGlobalRequestParameters() { 
    List<RequestParameter> parameters=new ArrayList<>(); parameters.add(new RequestParameterBuilder() .name("uuid") .description("设备uuid") .required(true) .in(ParameterType.QUERY) .query(q->q.model(m->m.scalarModel((ScalarType.STRING)))) .required(false) .build()); return parameters; } /* 封装通用相应信息 */ private List<Response> getGlobalResponseMessage() { 
    List<Response> responseList=new ArrayList<>(); responseList.add(new ResponseBuilder().code("404").description("未找到资源").build()); return responseList; } } 

通过以上配置已经完成了Spring Boot与Swagger的集成，下面展示一下如何在业务逻辑中进行使用。

业务中使用

创建两个实体类Goods（商品类）和CommonResult（通用返回结果类）。

Goods类：

package cn.itcast.swagger.model; import io.swagger.annotations.ApiModel; import io.swagger.annotations.ApiModelProperty; import java.math.BigDecimal; @ApiModel("商品模型") public class Goods { 
    /* 商品id */ @ApiModelProperty("商品ID") Long goodsId; /* 商品名称 */ @ApiModelProperty("商品名称") private String goodsName; /* 商品加个 */ @ApiModelProperty("商品价格") private BigDecimal price; public Long getGoodsId() { 
    return goodsId; } public void setGoodsId(Long goodsId) { 
    this.goodsId = goodsId; } public String getGoodsName() { 
    return goodsName; } public void setGoodsName(String goodsName) { 
    this.goodsName = goodsName; } public BigDecimal getPrice() { 
    return price; } public void setPrice(BigDecimal price) { 
    this.price = price; } } 

CommonResult类：

package cn.itcast.swagger.model; import io.swagger.annotations.ApiModel; import io.swagger.annotations.ApiModelProperty; /* @ApiModel: 用于请求的方法上，表示一组响应 (这种一般用在post创建的时候,使用@RequestBody这样的场景) 请求参数无法使用@ApiImplicitParam注解进行描述的时候 */ @ApiModel("API通用数据") public class CommonResult<T>{ 
    /* 标识代码 0表示成功，非0表示出错 @ApiModelProperty：用在属性上，描述响应类的属性 */ @ApiModelProperty("标识代码,0表示成功,非0表示出错") private Integer code; /* 描述信息，通常错时使用 */ @ApiModelProperty("错误描述") private String msg; /* 业务数据 */ @ApiModelProperty("业务数据") private T data; public CommonResult(Integer code, String msg, T data) { 
    this.code = code; this.msg = msg; this.data = data; } /* 成功 */ public static <T> CommonResult<T> success(T data){ 
    return new CommonResult<>(0,"成功",data); } public static <T> CommonResult<T> success(Integer code,String msg){ 
    return new CommonResult<>(code,msg,null); } /* 错误 */ public static <T> CommonResult<T> error(Integer code,String msg){ 
    return new CommonResult<>(code,msg,null); } public Integer getCode() { 
    return code; } public void setCode(Integer code) { 
    this.code = code; } public String getMsg() { 
    return msg; } public void setMsg(String msg) { 
    this.msg = msg; } public T getData() { 
    return data; } public void setData(T data) { 
    this.data = data; } } 

下面针对Controller层的接口来使用Swagger对应的API。

GoodsController类：

package cn.itcast.swagger.controller; import cn.itcast.swagger.model.CommonResult; import cn.itcast.swagger.model.Goods; import io.swagger.annotations.Api; import io.swagger.v3.oas.annotations.Operation; import io.swagger.v3.oas.annotations.Parameter; import org.springframework.web.bind.annotation.GetMapping; import org.springframework.web.bind.annotation.RequestMapping; import org.springframework.web.bind.annotation.RequestParam; import org.springframework.web.bind.annotation.RestController; import java.math.BigDecimal; @Api(tags="商品信息管理接口") @RestController @RequestMapping("/goods") public class GoodsController { 
    @Operation(summary ="单个商品详情") @GetMapping("/findGoodsById") public CommonResult<Goods> findGoodsById( @Parameter(description = "商品ID,正整数") @RequestParam(value="goodsId",required = false,defaultValue = "0") Integer goodsId) { 
    System.out.println("根据商品ID="+goodsId+"查询商品详情"); Goods goods=new Goods(); goods.setGoodsId(1L); goods.setGoodsName("笔记本"); goods.setPrice(new BigDecimal(8888)); return CommonResult.success(goods); } } 

OrderController类：

package cn.itcast.swagger.controller; import cn.itcast.swagger.model.CommonResult; import io.swagger.annotations.Api; import io.swagger.annotations.ApiImplicitParam; import io.swagger.annotations.ApiImplicitParams; import io.swagger.v3.oas.annotations.Operation; import org.springframework.web.bind.annotation.PostMapping; import org.springframework.web.bind.annotation.RequestMapping; import org.springframework.web.bind.annotation.RequestParam; import org.springframework.web.bind.annotation.RestController; import springfox.documentation.annotations.ApiIgnore; import java.util.Map; //@Api用在请求的类上，表示对类的说明 tags说明该类的作用，可以在UI界面上看到注解 @Api(tags="订单管理接口") @RestController @RequestMapping("/order") public class OrderController { 
    /* @ApiImplicitParams: 用在请求的方法上，说明方法的用途，作用 @ApiImplicitParam：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面 name:参数名 value:参数的汉字说明，解释 required:参数是否必须传 paramType:参数放在哪个地方 · header --> 请求参数的获取：@RequestHeader · query --> 请求参数的获取：@RequestParam · path（用于restful接口）--> 请求参数的获取：@PathVariable · body（不常用） · form（不常用） dataType:参数类型，默认String,其他值dataType="Integer" defaultValue:参数的默认值 */ @Operation(summary ="提交订单") @PostMapping("/order") @ApiImplicitParams({ 
    @ApiImplicitParam(name="userId",value="用户Id",dataTypeClass = Long.class, paramType = "query",example ="123"), @ApiImplicitParam(name="goodsId",value="商品Id",dataTypeClass = Integer.class, paramType = "query",example ="1") }) public CommonResult<String> toBuy(@ApiIgnore @RequestParam Map<String,String> params){ 
    System.out.println(params); return CommonResult.success("success"); } } 

4. 查看结果

从整体上可以看到如下效果：

具体的商品信息管理接口，可以看到请求参数、返回结果数据结构等信息，点击“Try it out”，可输入参数请求参数，进行接口的调用：

调用之后会返回对应的处理结果：

在最下面的Schemas中还可以看到对应返回结果数据和被Swagger注解的实体类信息。

5. Swagger3注解使用说明

经过上述实例之后，我们知道大多数API是如何使用的了，这了再汇总一下相关API的功能：

6. 导出离线文档

Swagger为我们提供了方便的在线文档支持，但某些场景下我们需要把接口文档提供给合作人员，而不是直接给一个地址。此时，我们就需要将接口文档导出为离线文档。

这里我们集成增强文档knife4j来实现离线文档的导出。

添加knife4j依赖

在pom.xml中增加knife4j的依赖：

 <dependency> <groupId>com.github.xiaoymin 
     groupId> <artifactId>knife4j-spring-boot-starter 
      artifactId> <version>3.0.2 
       version>  
        dependency> 

启动knife4j

在上面配置Swagger的Swagger3Config中添加@EnableKnife4j注解，该注解可以开启knife4j的增强功能。

@EnableKnife4j @Configuration @EnableOpenApi public class Swagger3Config { // ... } 

此时，如果依旧访问http://localhost:8080/swagger-ui/index.html会发现显示并没有变化。这里我们需要访问http://localhost:8080/doc.html。

展示效果

此时启动项目，访问doc.html之后，你会发现现在文档风格变得非常酷炫。展示几个效果图来看看：

其中在“离线文档”一栏中可以看到四种形式的离线文档下载：Markdown、HTML、Word、OpenAPI。

其中个人感觉HTML格式的文档更具有美感，也更方便查看，来一张图看看效果。