前言

SpringBoot系列Demo代碼，使用 Swagger UI實(shí)現(xiàn)對(duì)API接口文檔的管理。

一、Swagger UI是什么？

Swagger UI是可視化實(shí)時(shí)API文檔，按照規(guī)范寫(xiě)好接口代碼后，直接實(shí)時(shí)查看、測(cè)試API，無(wú)需再單獨(dú)編寫(xiě)API文檔，省時(shí)省力,支持在線(xiàn)導(dǎo)入描述文件和本地部署UI項(xiàng)目。

Swagger UI官網(wǎng)：https://swagger.io/tools/swagger-ui/

二、使用步驟

1.引入依賴(lài)

<!-- 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.編寫(xiě)配置類(lèi)

/**
 * @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基礎(chǔ)掃描路徑
                .apis(RequestHandlerSelectors.basePackage("com.local.dev.root.devroot.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("SpringBootDemo-API實(shí)時(shí)接口文檔")
                .description("用于管理、查看、測(cè)試API")
                .contact(new Contact("MaoDeShu", "https://blog.csdn.net/qq_34383510", "1474538220@qq.com"))
                .version("version 1.0")
                .build();
    }
}

3.修改接口信息

controller

@Api(value = "用戶(hù)管理相關(guān)接口", tags = "用戶(hù)管理相關(guān)接口")
@RestController
@RequestMapping("/user")
public class SysUserController {

    @Autowired
    private SysUserService sysUserService;

    @ApiOperation(value = "查詢(xún)用戶(hù)信息", notes = "根據(jù)手機(jī)號(hào)或openId查詢(xún)用戶(hù)信息")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "param", required = true, value = "手機(jī)號(hào)或openId"),
    })
    @PostMapping("/getUserByCondition")
    public ApiResponse getUserByCondition(@RequestParam String param) {
        SysUser user = sysUserService.getByPhoneOrOpenId(param);
        return ApiResponse.ok(user);
    }

    @ApiOperation(value = "獲取用戶(hù)列表", notes = "分頁(yè)查詢(xún)所有用戶(hù)信息")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "pageNumber", required = true, value = "當(dāng)前頁(yè)"),
            @ApiImplicitParam(name = "pageSize", required = true, value = "頁(yè)容量"),
            @ApiImplicitParam(name = "keyword", required = false, value = "關(guān)鍵字查詢(xún)"),
    })
    @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);
    }
}

如果有實(shí)體類(lèi)做參數(shù)，需要在類(lèi)和屬性上加上@ApiModel(description = "User實(shí)體Vo") @ApiModelProperty("用戶(hù)名稱(chēng)")

三、測(cè)試

1.查看API文檔

瀏覽器地址輸入http://localhost:8080/swagger-ui.html#/

在這里插入圖片描述

可以看到接口，打開(kāi)用戶(hù)管理接口，進(jìn)行測(cè)試

在這里插入圖片描述

得到結(jié)果如下圖：

在這里插入圖片描述

2.測(cè)試中出現(xiàn)的問(wèn)題

第一次測(cè)試時(shí)，出現(xiàn)：MissingServletRequestParameterException: Required request parameter 'keyword' for method parameter type String is not present]

在這里插入圖片描述

在這里插入圖片描述

在這里插入圖片描述

四、集成Swagger-Bootstrap-UI

1.添加Maven依賴(lài)

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

文檔：https://doc.xiaominfo.com/
開(kāi)源項(xiàng)目地址：https://github.com/xiaoymin/Swagger-Bootstrap-UI

2.啟動(dòng)項(xiàng)目

啟動(dòng)項(xiàng)目，然后訪問(wèn)地址:http://localhost:8080/doc.html即可

在這里插入圖片描述

在這里插入圖片描述

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

創(chuàng)作不易，關(guān)注、點(diǎn)贊就是對(duì)作者最大的鼓勵(lì)，歡迎在下方評(píng)論留言
求關(guān)注，定期分享Java知識(shí)，一起學(xué)習(xí)，共同成長(zhǎng)。