SpringBoot —— Swagger UI、Swagger-Bootstrap-UI，API实时接口文档

前言

SpringBoot系列Demo代码，使用 Swagger UI实现对API接口文档的管理。

一、Swagger UI是什么？

Swagger UI是可视化实时API文档，按照规范写好接口代码后，直接实时查看、测试API，无需再单独编写API文档，省时省力,支持在线导入描述文件和本地部署UI项目。

Swagger UI官网：https://swagger.io/tools/swagger-ui/

二、使用步骤

1.引入依赖

<!-- Swagger UI API接口-->
<dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger2</artifactId><version>2.9.2</version>
</dependency>
<dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger-ui</artifactId><version>2.9.2</version>
</dependency>

2.编写配置类

/*** @author: MaoDeShu* @date: 2021-09-17 16:29* @Description: Swagger UI 配置信息**/
@Configuration
@EnableSwagger2
public class SwaggerConfig {
    /*** 添加摘要信息** @return*/@Beanpublic Docket createRestApi() {
    return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select()// API基础扫描路径.apis(RequestHandlerSelectors.basePackage("com.local.dev.root.devroot.controller")).paths(PathSelectors.any()).build();}private ApiInfo apiInfo() {
    return new ApiInfoBuilder().title("SpringBootDemo-API实时接口文档").description("用于管理、查看、测试API").contact(new Contact("MaoDeShu", "https://blog.csdn.net/qq_34383510", "1474538220@qq.com")).version("version 1.0").build();}
}

3.修改接口信息

controller

@Api(value = "用户管理相关接口", tags = "用户管理相关接口")
@RestController
@RequestMapping("/user")
public class SysUserController {
    @Autowiredprivate SysUserService sysUserService;@ApiOperation(value = "查询用户信息", notes = "根据手机号或openId查询用户信息")@ApiImplicitParams({
    @ApiImplicitParam(name = "param", required = true, value = "手机号或openId"),})@PostMapping("/getUserByCondition")public ApiResponse getUserByCondition(@RequestParam String param) {
    SysUser user = sysUserService.getByPhoneOrOpenId(param);return ApiResponse.ok(user);}@ApiOperation(value = "获取用户列表", notes = "分页查询所有用户信息")@ApiImplicitParams({
    @ApiImplicitParam(name = "pageNumber", required = true, value = "当前页"),@ApiImplicitParam(name = "pageSize", required = true, value = "页容量"),@ApiImplicitParam(name = "keyword", required = false, value = "关键字查询"),})@GetMapping("/list")public ApiResponse list(@RequestParam(required = false) String keyword,@RequestParam Integer pageNumber,@RequestParam Integer pageSize) {
    Page page = sysUserService.selectPage(pageNumber, pageSize, keyword);return ApiResponse.ok(page);}
}

如果有实体类做参数，需要在类和属性上加上@ApiModel(description = "User实体Vo") @ApiModelProperty("用户名称")

三、测试

1.查看API文档

浏览器地址输入http://localhost:8080/swagger-ui.html#/

可以看到接口，打开用户管理接口，进行测试

得到结果如下图：

2.测试中出现的问题

第一次测试时，出现：MissingServletRequestParameterException: Required request parameter 'keyword' for method parameter type String is not present]


可以看到时参数的问题，查看代码

发现keyword不是必须的，所以加上@RequestParam(required = false) String keyword，成功解决问题。

四、集成Swagger-Bootstrap-UI

1.添加Maven依赖

<!-- swagger-bootstrap-ui-->
<dependency><groupId>com.github.xiaoymin</groupId><artifactId>swagger-bootstrap-ui</artifactId><version>1.9.6</version>
</dependency>

文档：https://doc.xiaominfo.com/
开源项目地址：https://github.com/xiaoymin/Swagger-Bootstrap-UI

2.启动项目

启动项目，然后访问地址:http://localhost:8080/doc.html即可

测试接口，效果图如下:

? 上一章：SpringBoot —— 整合MyBatis-Plus
? 下一章：SpringBoot —— 整合Logback，输出日志到文件