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

文章目录

• 前言
• 一、Swagger UI是什么？
• 二、使用步骤
• • 1.引入依赖
  • 2.编写配置类
  • 3.修改接口信息
• 三、测试
• • 1.查看API文档
  • 2.测试中出现的问题
• 四、集成Swagger-Bootstrap-UI
• • 1.添加Maven依赖
  • 2.启动项目

前言

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
     */
    @Bean
    public 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 {

    @Autowired
    private 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，输出日志到文件