1. 关于Swagger
Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。
相信采用 Spring Boot 开发的小伙伴几乎是用来构建 RESTful API ，而文档自然是不可缺少的一部分，Swagger 的出现，既可以减少我们创建文档的工作量，同时说明内容又整合入实现代码中，让维护文档和修改代码整合为一体，可以让我们在修改代码逻辑的同时方便的修改文档说明。
另外Swagger2也提供了强大的页面测试功能来调试每个RESTful API。
作用总结：
- 接口文档在线生成
- 方便功能测试
集成后的效果图如下：
2. 开始集成
2.1 添加依赖
在 pom.xml 中添加 swagger 依赖
<!-- Swagger API文档 -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.7.0</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.7.0</version>
</dependency>
2.2 配置Swagger
applicaton.yml
# Swagger界面内容配置
swagger:
title: TMax API接口文档
description: TMax Api Documentation
version: 1.0.0
termsOfServiceUrl: https://www.sscai.club
contact:
name: niceyoo
url: https://www.sscai.club
email: apkdream@163.com
如上配置请置于根节点，如下图所示：
Swagger2Config.java
新建一个 Swagger2Config.java 的配置类：
- 添加 @Configuration 注解，用于定义配置类，方便被Spring Boot配置；
- 添加 @EnableSwagger2 注解启动 Swagger 文档构建能力。
完整代码如下：
@Slf4j
@Configuration
@EnableSwagger2
public class Swagger2Config {
@Value("${swagger.title}")
private String title;
@Value("${swagger.description}")
private String description;
@Value("${swagger.version}")
private String version;
@Value("${swagger.termsOfServiceUrl}")
private String termsOfServiceUrl;
@Value("${swagger.contact.name}")
private String name;
@Value("${swagger.contact.url}")
private String url;
@Value("${swagger.contact.email}")
private String email;
private List<ApiKey> securitySchemes() {
List<ApiKey> apiKeys = new ArrayList<>();
apiKeys.add(new ApiKey("Authorization", "accessToken", "header"));
return apiKeys;
}
private List<SecurityContext> securityContexts() {
List<SecurityContext> securityContexts = new ArrayList<>();
securityContexts.add(SecurityContext.builder()
.securityReferences(defaultAuth())
.forPaths(PathSelectors.regex("^(?!auth).*$")).build());
return securityContexts;
}
private List<SecurityReference> defaultAuth() {
AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything");
AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];
authorizationScopes[0] = authorizationScope;
List<SecurityReference> securityReferences = new ArrayList<>();
securityReferences.add(new SecurityReference("Authorization", authorizationScopes));
return securityReferences;
}
@Bean
public Docket createRestApi() {
log.info("加载Swagger2");
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo()).select()
## 扫描所有有注解的api，用这种方式更灵活
.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
.paths(PathSelectors.any())
.build()
.securitySchemes(securitySchemes())
.securityContexts(securityContexts());
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title(title)
.description(description)
.termsOfServiceUrl(termsOfServiceUrl)
.contact(new Contact(name, url, email))
.version(version)
.build();
}
}
方法讲解：
通过 createRestfulApiDocs() 方法创建 Docket 的 Bean 之后，apiInfo() 用来创建该 API 的基本信息。（这些基本信息会展现在文档页面中，如最开始的预览图，增加一些文档自定义信息）
select() 函数返回一个 ApiSelectorBuilder 实例用来控制哪些接口暴露给Swagger 来展现，本例采用扫描所有带有 API 注解的对外开放，同时，你也可以采用指定扫描的包路径来定义，Swagger 则会扫描该包下所有 Controller定义的 API，并产生文档内容（除了被@ApiIgnore指定的请求）。
如果采用扫描指定包路径的话，需要修改 createRestApi() 方法的 apis 部分：
.apis(RequestHandlerSelectors.basePackage("com.lemon.security.web.controller"))
2.3 新建entity和controller测试
entity：VideoCategory.java
@Data
@Entity
@Table(name = "v_category")
@TableName("v_category")
@ApiModel(value = "视频类型")
public class VideoCategory extends TmaxBaseEntity {
private static final long serialVersionUID = 1L;
@ApiModelProperty(value = "类型名称")
private String title;
@ApiModelProperty(value = "排序值")
@Column(precision = 10, scale = 2)
private BigDecimal sortOrder;
@ApiModelProperty(value = "是否启用 0启用 -1禁用")
private Integer status = CommonConstant.STATUS_NORMAL;
}
controller：VideoCategoryController 主要以添加、查询为例
@Slf4j
@RestController
@Api(description = "视频类型管理接口")
@RequestMapping("/tmax/videoCategory")
@Transactional
public class VideoCategoryController extends TmaxBaseController<VideoCategory, String> {
@Autowired
private VideoCategoryService videoCategoryService;
@Override
public VideoCategoryService getService() {
return videoCategoryService;
}
@RequestMapping(value = "/add", method = RequestMethod.POST)
@ApiOperation(value = "添加")
public Result<Object> add(@ModelAttribute VideoCategory videoCategory){
VideoCategory d = videoCategoryService.save(videoCategory);
return new ResultUtil<Object>().setSuccessMsg("添加成功");
}
@RequestMapping(value = "/search", method = RequestMethod.GET)
@ApiOperation(value = "分类名模糊搜索")
public Result<List<VideoCategory>> searchByTitle(
@RequestParam String title,
@ApiParam("是否开始数据权限过滤") @RequestParam(required = false, defaultValue = "true") Boolean openDataFilter){
List<VideoCategory> list = videoCategoryService.findByTitleLikeOrderBySortOrder("%"+title+"%", openDataFilter);
return new ResultUtil<List<VideoCategory>>().setData(list);
}
}
常用注解说明：
- @Api()用于类；
表示标识这个类是swagger的资源 - @ApiOperation()用于方法；
表示一个http请求的操作 - @ApiParam()用于方法，参数，字段说明；
表示对参数的添加元数据（说明或是否必填等） - @ApiModel()用于类
表示对类进行说明，用于参数用实体类接收 - @ApiModelProperty()用于方法，字段
表示对model属性的说明或者数据操作更改 - @ApiIgnore()用于类，方法，方法参数
表示这个方法或者类被忽略 - @ApiImplicitParam() 用于方法
表示单独的请求参数 - @ApiImplicitParams() 用于方法，包含多个 @ApiImplicitParam
项目启动后访问：http://localhost:端口号(例如8080)/swagger-ui.html
我们尝试操作一下 add() 方法：
- 填写实体基本信息
- 点击 Try it out! 按钮
3. 最后
在上边的整个过程中，我们了解 Swagger 除了查看接口功能外，还提供了调试测试功能，点击“Try it out！”按钮，即可完成了一次请求调用！
此时，你也可以通过几个 POST 请求来验证之前的 POST 请求是否正确。相比为这些接口编写文档的工作，我们增加的配置内容是非常少而且精简的，对于原有代码的侵入也在忍受范围之内。
因此，在构建 RESTful API 的同时，加入 Swagger 来对 API 文档进行管理，是个不错的选择。