前言

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