springboot 之 整合springdoc2.6 (swagger 3)

版本

springboot 3.3.5

jdk 17

springdoc 2.6.0

依赖pom

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.6.0</version>
</dependency>

注解对比 swagger 2 与 3

可选：配置信息(如果没啥特殊配置，可以不写)

package com.test.swagger.config;

import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Contact;
import io.swagger.v3.oas.models.info.Info;
import io.swagger.v3.oas.models.info.License;
import org.springdoc.core.models.GroupedOpenApi;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class SpringDocConfig {

    @Bean
    public OpenAPI openAPI(){
        return new OpenAPI()
                //设置接口文档基本信息
                .info(this.getOpenApiInfo());
    }

    private Info getOpenApiInfo(){
        return new Info()
                //标题
                .title("SpringBoot3集成springDoc")
                //描述
                .description("SpringBoot3集成springDoc示例文档")
                //作者信息
                .contact(new Contact().name("enjoy").url("").email("123456789@qq.com"))
                .license(new License().name("apache 2.0").url("这是个假的url"))
                //概述信息
                .summary("springboot 3.3 集成 springdoc 2.6")
                .termsOfService("这是个假的url")
                //版本
                .version("3.x - 2.6");
    }

    /**
     * 接口分组
     */
    @Bean("AGroupApi")
    public GroupedOpenApi agroupedOpenApi(){
        return GroupedOpenApi.builder()
                .group("AGroupApi")
                .pathsToMatch("/person/**")
                .build();
    }

    /**
     * 接口分组
     */
    @Bean("BGroupApi")
    public GroupedOpenApi bgroupedOpenApi(){
        return GroupedOpenApi.builder()
                .group("BGroupApi")
                .pathsToMatch("/person/**")
                .build();
    }
}

实体类

package com.test.swagger.entity;
import io.swagger.v3.oas.annotations.media.Schema;
import lombok.Data;

@Data
@Schema(description = "用户实体类")
public class Person {
    /**
     * 真实姓名
     */
    @Schema(description = "用户名称", requiredMode = Schema.RequiredMode.REQUIRED)
    private String userName;
    /**
     * 地址
     */
    @Schema(description = "用户地址")
    private String address;
    /**
     * 电话号码
     */
    @Schema(description = "用户电话")
    private String phoneNumber;
    /**
     * 身份证号码
     */
    @Schema(description = "用户地址")
    private String idCard;
}

接口类

package com.test.swagger.controller;

import com.test.swagger.entity.Person;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.media.Content;
import io.swagger.v3.oas.annotations.media.Schema;
import io.swagger.v3.oas.annotations.responses.ApiResponse;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.web.bind.annotation.*;

/**
 * http://localhost:8080/swagger-ui/index.html
 * 访问接口地址
 */
@RestController
@RequestMapping(value = "/person")
@Tag(name = "person接口" , description = "这只是一个描述")
public class SwaggerTestApiController {

    @Operation(
            summary = "根据Id查询用户信息", description = "根据ID查询用户信息，并返回响应结果信息",
            //入参
            parameters = {
                    @Parameter(name = "id", description = "用户ID", required = true, example = "1")
            },
            //返回值
            responses = {
                    @ApiResponse(
                            responseCode = "200",
                            description = "响应成功",
                            content = @Content(
                                    mediaType = "application/json",
                                    schema = @Schema(
                                            title = "实体类",
                                            description = "返回实体",
                                            implementation = Person.class
                                    )
                            )
                    ),
                    @ApiResponse(
                            responseCode = "500",
                            description = "响应失败",
                            content = @Content(schema = @Schema())
                    )
            }
    )
    @GetMapping("hello")
    public Person getHello(){
        Person user = new Person();
        user.setUserName("小明");
        user.setPhoneNumber("123456789");
        user.setAddress("中国辽宁省葫芦岛");
        user.setIdCard("52462545262256562");
        return user;
    }

    @Operation(summary = "新增用户", description = "新增用户",
            responses ={
                    @ApiResponse(
                            responseCode = "200",
                            content = { @Content(schema = @Schema(implementation = Person.class), mediaType = "application/json") }),
                    @ApiResponse(
                            responseCode = "404",
                            description = "User not found.", content = { @Content(schema = @Schema()) })
            }
    )
    @PostMapping("addPerson")
    public Person addPerson(@RequestBody Person person){
        Person user = new Person();
        user.setUserName("小明");
        user.setPhoneNumber("123456789");
        user.setAddress("中国辽宁省葫芦岛");
        user.setIdCard("52462545262256562");
        return user;
    }

    @DeleteMapping("deletePerson/{id}")
//    @Operation(summary = "新增用户", description = "新增用户", hidden = true)
//    @Hidden
    public boolean deletePerson(
            @Parameter(description = "用户id")
            @PathVariable int id){
        System.out.println("deletePerson: " + id);
        return true;
    }

    @PutMapping("editPerson")
    public Person editPerson(
            @io.swagger.v3.oas.annotations.parameters.RequestBody(description = "User to add.", required = true)
            @RequestBody Person person){
        System.out.println("editPerson");
        return null;
    }
}

测试

运行项目，访问地址： http://localhost:8080/swagger-ui/index.html

web总览

接口详情

总结

现在接口开发和测试插件各种各样，接口文档生成插件也非常多，真没必要只关注swagger一个。写接口文档相关代码都比实际接口代码都多了，真的麻烦。

实际开发中，接口在设计初期就已经有相关文档，如果测试接口，可以直接使用 cool request插件直接在IDEA测试。如果说后面需要在接口改动后再次生成接口文档，也可以使用其他插件，比如 JApiDocs , 自动生成接口文档了。