当前位置: 代码迷 >> 综合 >> SpringBoot —— Swagger UI、Swagger-Bootstrap-UI,API实时接口文档
  详细解决方案

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

热度:78   发布时间:2023-09-18 12:50:30

文章目录

  • 前言
  • 一、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*/@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#/

SpringBoot —— Swagger UI、Swagger-Bootstrap-UI,API实时接口文档
可以看到接口,打开用户管理接口,进行测试
SpringBoot —— Swagger UI、Swagger-Bootstrap-UI,API实时接口文档
得到结果如下图:
SpringBoot —— Swagger UI、Swagger-Bootstrap-UI,API实时接口文档

2.测试中出现的问题

第一次测试时,出现:MissingServletRequestParameterException: Required request parameter 'keyword' for method parameter type String is not present]
SpringBoot —— Swagger UI、Swagger-Bootstrap-UI,API实时接口文档
SpringBoot —— Swagger UI、Swagger-Bootstrap-UI,API实时接口文档
可以看到时参数的问题,查看代码
SpringBoot —— Swagger UI、Swagger-Bootstrap-UI,API实时接口文档
发现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 —— Swagger UI、Swagger-Bootstrap-UI,API实时接口文档
测试接口,效果图如下:
SpringBoot —— Swagger UI、Swagger-Bootstrap-UI,API实时接口文档

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