SpringBoot集成Swagger3 —— 教你如何优雅的写文档
Swagger介绍及使用导语：相信无论是前端还是后端开发，都或多或少地被接口文档折磨过。前端经常抱怨后端给的接口文档与实际情况不一致。后端又觉得编写及维护接口文档会耗费不少精力，经常来不及更新。其实无论是前端调用后端，还是后端调用后端，都期望有一个好的接口文档。但是这个接口文档对于程序员来说，就跟注释一样，经常会抱怨别人写的代码没有写注释，然而自己写起代码起来，最讨厌的，也是写注释。所以仅仅只通过
·
Swagger介绍及使用
导语：
相信无论是前端还是后端开发，都或多或少地被接口文档折磨过。前端经常抱怨后端给的接口文档与实际情况不一致。后端又觉得编写及维护接口文档会耗费不少精力，经常来不及更新。其实无论是前端调用后端，还是后端调用后端，都期望有一个好的接口文档。但是这个接口文档对于程序员来说，就跟注释一样，经常会抱怨别人写的代码没有写注释，然而自己写起代码起来，最讨厌的，也是写注释。所以仅仅只通过强制来规范大家是不够的，随着时间推移，版本迭代，接口文档往往很容易就跟不上代码了。
Swagger简介
- Swagger是一个开源的软件框架，可以帮助开发人员设计、构建和使用Web服务，将代码与文档结合在一起，完美的解决了上述问题，使开发人员将大部分精力集中到业务中，而不是文档的撰写。
官网：https://swagger.io
Swagger解决的痛点
传统方式提供文档有以下痛点：
- 文档需要更新的时候，需要再次发送一份给前端，也就是文档更新交流不及时。
- 接口返回结果不明确
- 不能直接在线测试接口，通常需要使用工具，比如postman
- 接口文档太多，不好管理
Swagger也就是为了解决这个问题，当然也不能说Swagger就一定是完美的，当然也有缺点，最明显的就是代码移入性比较强。
Swagger3的改变
Swagger3.0的改动，官方文档总结如下几点：
- 删除了对springfox-swagger2的依赖；
- 删除所有@EnableSwagger2…注解；
- 添加了springfox-boot-starter依赖项；
- 移除了guava等第三方依赖；
- 文档访问地址改为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","baidu@qq.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. 查看结果
完成集成，启动SpringBoot项目，在访问地址：
从整体上可以看到如下效果：
具体的商品信息管理接口，可以看到请求参数、返回结果数据结构等信息，点击“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格式的文档更具有美感，也更方便查看，来一张图看看效果。
为开发者提供学习成长、分享交流、生态实践、资源工具等服务，帮助开发者快速成长。
更多推荐
43
0- 0
已为社区贡献3条内容
所有评论(0)