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

绝地灬酷狼 2023-10-05 21:50 66阅读 0赞

#### 文章目录 ####

*  前言
 *  一、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/][https_swagger.io_tools_swagger-ui]

## 二、使用步骤 ##

### 1.引入依赖 ###

<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#/`

![在这里插入图片描述][watermark_type_ZHJvaWRzYW5zZmFsbGJhY2s_shadow_50_text_Q1NETiBALueMq-eahOagkQ_size_20_color_FFFFFF_t_70_g_se_x_16]  
可以看到接口，打开用户管理接口，进行测试  
![在这里插入图片描述][watermark_type_ZHJvaWRzYW5zZmFsbGJhY2s_shadow_50_text_Q1NETiBALueMq-eahOagkQ_size_20_color_FFFFFF_t_70_g_se_x_16 1]  
得到结果如下图：  
![在这里插入图片描述][watermark_type_ZHJvaWRzYW5zZmFsbGJhY2s_shadow_50_text_Q1NETiBALueMq-eahOagkQ_size_20_color_FFFFFF_t_70_g_se_x_16 2]

### 2.测试中出现的问题 ###

第一次测试时，出现：`MissingServletRequestParameterException: Required request parameter 'keyword' for method parameter type String is not present]`  
![在这里插入图片描述][9e65cca23eea455da94df4329fd09d94.png]  
![在这里插入图片描述][watermark_type_ZHJvaWRzYW5zZmFsbGJhY2s_shadow_50_text_Q1NETiBALueMq-eahOagkQ_size_20_color_FFFFFF_t_70_g_se_x_16 3]  
可以看到时参数的问题，查看代码  
![在这里插入图片描述][watermark_type_ZHJvaWRzYW5zZmFsbGJhY2s_shadow_50_text_Q1NETiBALueMq-eahOagkQ_size_20_color_FFFFFF_t_70_g_se_x_16 4]  
发现keyword不是必须的，所以加上`@RequestParam(required = false) String keyword`，成功解决问题。

## 四、集成Swagger-Bootstrap-UI ##

### 1.添加Maven依赖 ###

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

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

### 2.启动项目 ###

启动项目，然后访问地址:`http://localhost:8080/doc.html`即可  
![在这里插入图片描述][watermark_type_ZHJvaWRzYW5zZmFsbGJhY2s_shadow_50_text_Q1NETiBALueMq-eahOagkQ_size_20_color_FFFFFF_t_70_g_se_x_16 5]  
测试接口，效果图如下:  
![在这里插入图片描述][watermark_type_ZHJvaWRzYW5zZmFsbGJhY2s_shadow_50_text_Q1NETiBALueMq-eahOagkQ_size_20_color_FFFFFF_t_70_g_se_x_16 6]

[«][Link 1] 上一章：[SpringBoot —— 整合MyBatis-Plus][Link 1]  
[»][Link 2] 下一章：[SpringBoot —— 整合Logback，输出日志到文件][Link 2]

[https_swagger.io_tools_swagger-ui]: https://swagger.io/tools/swagger-ui/
[watermark_type_ZHJvaWRzYW5zZmFsbGJhY2s_shadow_50_text_Q1NETiBALueMq-eahOagkQ_size_20_color_FFFFFF_t_70_g_se_x_16]: https://img-blog.csdnimg.cn/7a9036666a2249088a02cbd4c05c2260.png?x-oss-process=image/watermark,type_ZHJvaWRzYW5zZmFsbGJhY2s,shadow_50,text_Q1NETiBALueMq-eahOagkQ==,size_20,color_FFFFFF,t_70,g_se,x_16
[watermark_type_ZHJvaWRzYW5zZmFsbGJhY2s_shadow_50_text_Q1NETiBALueMq-eahOagkQ_size_20_color_FFFFFF_t_70_g_se_x_16 1]: https://img-blog.csdnimg.cn/973378ddc6ab4ac799dd361ec54ae748.png?x-oss-process=image/watermark,type_ZHJvaWRzYW5zZmFsbGJhY2s,shadow_50,text_Q1NETiBALueMq-eahOagkQ==,size_20,color_FFFFFF,t_70,g_se,x_16
[watermark_type_ZHJvaWRzYW5zZmFsbGJhY2s_shadow_50_text_Q1NETiBALueMq-eahOagkQ_size_20_color_FFFFFF_t_70_g_se_x_16 2]: https://img-blog.csdnimg.cn/3395763efb754a5689aaf2e018f386fc.png?x-oss-process=image/watermark,type_ZHJvaWRzYW5zZmFsbGJhY2s,shadow_50,text_Q1NETiBALueMq-eahOagkQ==,size_20,color_FFFFFF,t_70,g_se,x_16
[9e65cca23eea455da94df4329fd09d94.png]: https://img-blog.csdnimg.cn/9e65cca23eea455da94df4329fd09d94.png
[watermark_type_ZHJvaWRzYW5zZmFsbGJhY2s_shadow_50_text_Q1NETiBALueMq-eahOagkQ_size_20_color_FFFFFF_t_70_g_se_x_16 3]: https://img-blog.csdnimg.cn/c7239f761a62446b8061314b96ded274.png?x-oss-process=image/watermark,type_ZHJvaWRzYW5zZmFsbGJhY2s,shadow_50,text_Q1NETiBALueMq-eahOagkQ==,size_20,color_FFFFFF,t_70,g_se,x_16
[watermark_type_ZHJvaWRzYW5zZmFsbGJhY2s_shadow_50_text_Q1NETiBALueMq-eahOagkQ_size_20_color_FFFFFF_t_70_g_se_x_16 4]: https://img-blog.csdnimg.cn/528dbd1fcf9248069a74b2defa460900.png?x-oss-process=image/watermark,type_ZHJvaWRzYW5zZmFsbGJhY2s,shadow_50,text_Q1NETiBALueMq-eahOagkQ==,size_20,color_FFFFFF,t_70,g_se,x_16
[https_doc.xiaominfo.com]: https://doc.xiaominfo.com/
[https_github.com_xiaoymin_Swagger-Bootstrap-UI]: https://github.com/xiaoymin/Swagger-Bootstrap-UI
[watermark_type_ZHJvaWRzYW5zZmFsbGJhY2s_shadow_50_text_Q1NETiBALueMq-eahOagkQ_size_20_color_FFFFFF_t_70_g_se_x_16 5]: https://img-blog.csdnimg.cn/4095727b2e464874b8d964a7a4175565.png?x-oss-process=image/watermark,type_ZHJvaWRzYW5zZmFsbGJhY2s,shadow_50,text_Q1NETiBALueMq-eahOagkQ==,size_20,color_FFFFFF,t_70,g_se,x_16
[watermark_type_ZHJvaWRzYW5zZmFsbGJhY2s_shadow_50_text_Q1NETiBALueMq-eahOagkQ_size_20_color_FFFFFF_t_70_g_se_x_16 6]: https://img-blog.csdnimg.cn/f0a0e880e1304524981c5d23214cbbbb.png?x-oss-process=image/watermark,type_ZHJvaWRzYW5zZmFsbGJhY2s,shadow_50,text_Q1NETiBALueMq-eahOagkQ==,size_20,color_FFFFFF,t_70,g_se,x_16
[Link 1]: https://blog.csdn.net/qq_34383510/article/details/120349228?spm=1001.2014.3001.5501
[Link 2]: https://blog.csdn.net/qq_34383510/article/details/120370010?spm=1001.2014.3001.5501