spring boot 集成springfox，使用swagger对 API 接口进行测试管理的 demo 示例

1. 描述

一个springboot项目集成 springfox 3.0，使用swagger对 API 接口进行测试管理的 demo示例。

环境：

IDE(idea)：2021.3
JDK：1.8
maven：3.8.4
spring boot：2.5.6
springfox：3.0.0

2. 结果

• 页面访问：http://localhost:8880/demo/swagger-ui/index.html
  

3. demo

3.0 项目结构

3.1 pom.xml

• 引入 springfox jar包

        <!-- springfox 3.X API doc框架， eg: swagger功能 -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-boot-starter</artifactId>
        </dependency>

3.2 SpringBootApplication 注解实现启动类

@SpringBootApplication
public class DemoSwaggerUiApplication {
    public static void main(String[] args) {
        SpringApplication.run(DemoSwaggerUiApplication.class, args);
        System.out.println("----- http://localhost:8880/demo/ -----");
        System.out.println("----- http://localhost:8880/demo/swagger-ui/index.html -----");
    }
}

3.3 application.yml配置

server:
  port: 8880
  servlet:
    context-path: /demo

3.4 其他代码

• Swagger3Config.java

@Configuration
@EnableOpenApi // swagger版本2用的 @EnableSwagger2
public class Swagger3Config {

    @Bean
    public Docket defaultApi() {
        return new Docket(DocumentationType.OAS_30)
                .groupName("default-api")
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.demo.swagger.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        String swaggerUrl = "http://localhost:8880/demo/swagger-ui/index.html";
        return new ApiInfoBuilder()
                .title("Swagger UI API")
                .description("Swagger UI API 的一个demo示例")
                .termsOfServiceUrl("http://localhost:8880/demo")
                .contact(new Contact("byrc", swaggerUrl, "best54288@163.com"))
                .license("Apache License Version 2.0")
                .licenseUrl("https://github.com/springfox/springfox/blob/master/LICENSE")
                .version("1.0.0")
                .build();
    }

• UserController .java

@Slf4j
@RestController
@RequestMapping("/user")
@Api(tags = "用户管理")
public class UserController {

    @GetMapping("/{id}")
    @ApiOperation(value = "主键查询", notes = "通过主键查询用户")
    public JsonResponse<User> get(@PathVariable @ApiParam("用户id") Integer id) {
        return JsonResponse.ok(new User(id, "白玉京", 23));
    }

    @DeleteMapping("/{id}")
    @ApiOperation(value = "删除用户", notes = "通过主键删除用户")
    public JsonResponse<String> delete(@PathVariable Integer id) {
        log.info("删除用户 {}", id);
        return JsonResponse.ok();
    }

    @PostMapping
    @ApiOperation(value = "添加用户")
    public JsonResponse<User> post(@RequestBody User user) {
        return JsonResponse.ok(user);
    }
}

4. 资料

• springfox 官网：http://springfox.github.io/springfox
• springfox github：https://github.com/springfox/springfox
• springfox demo: https://github.com/springfox/springfox-demos/blob/master/boot-swagger

5. 注

• spirng boot 已在父项目引入(父项目pom.xml配置）；
• 部分jar包版本已在父项目管理（如果对应不上，一定、肯定、决定是某些修改，没同步更新文档）。