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 {@Beanpublic 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)
//    @Hiddenpublic 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;}
}