springdoc-openapi使用

一、引入pom
二、新增配置类OpenApiConfig
四、Controller层示例
五、配置文件新增内容
六、验证

一、引入pom

        <dependency><groupId>org.springdoc</groupId><artifactId>springdoc-openapi-ui</artifactId><version>1.5.12</version></dependency>

二、新增配置类OpenApiConfig

@Configuration
public class OpenApiConfig {@Beanpublic OpenAPI springShopOpenAPI() {OpenAPI openAPI = new OpenAPI().info(new Info().title("制品中心 后台服务API接口文档").description("restful 风格接口").version("v0.0.1").license(new License().name("Apache 2.0").url("http://springdoc.org"))).externalDocs(new ExternalDocumentation().description("SpringShop Wiki Documentation").url("https://springshop.wiki.github.org/docs"));return openAPI;}@Beanpublic OperationCustomizer globalHeaderCustomizer() {//遍历所有操作(即接口)return (Operation operation, HandlerMethod handlerMethod) -> {//设置全局请求头参数setHeader(operation);return operation;};}private void setHeader(Operation operation){Parameter clusterIdParam = new Parameter().in(ParameterIn.HEADER.toString()).schema(new StringSchema()).name("clusterId").description("clusterId").required(false);Parameter tokenParam = new Parameter().in(ParameterIn.HEADER.toString()).schema(new StringSchema()).name("sessionid").description("sessionid").required(true);Parameter userIdParam = new Parameter().in(ParameterIn.HEADER.toString()).schema(new IntegerSchema()).name("userid").description("userid").required(true);Parameter useraccountParam = new Parameter().in(ParameterIn.HEADER.toString()).schema(new StringSchema()).name("useraccount").description("useraccount").required(true);Parameter userroleParam = new Parameter().in(ParameterIn.HEADER.toString()).schema(new StringSchema()).name("userrole").description("userrole").required(false);Parameter projectnameParam = new Parameter().in(ParameterIn.HEADER.toString()).schema(new StringSchema()).name("projectname").description("projectname").required(false);operation.addParametersItem(clusterIdParam);operation.addParametersItem(projectnameParam);operation.addParametersItem(tokenParam);operation.addParametersItem(useraccountParam);operation.addParametersItem(userIdParam);operation.addParametersItem(userroleParam);}@Beanpublic OpenApiCustomiser globalResponseCustomizer() {return openApi -> {openApi.getPaths().forEach((path, pathItem) -> {pathItem.readOperations().forEach(operation -> {ApiResponses responses = operation.getResponses();if(responses == null){responses = new ApiResponses();}// 添加全局响应addGlobalResponse(responses);// 将合并后的响应设置回操作operation.setResponses(responses);});});};}private void addGlobalResponse(ApiResponses responses){responses.addApiResponse("0",new ApiResponse().description("成功"));responses.addApiResponse("1",new ApiResponse().description("失败"));for (ServerStatus item : ServerStatus.values()) {responses.addApiResponse(String.valueOf(item.getErrorCode()),new ApiResponse().description(item.getMessage()));}}}

全局请求头参数设置参考文章：
https://stackoverflow.com/questions/63671676/springdoc-openapi-ui-add-jwt-header-parameter-to-generated-swagger

四、Controller层示例

@Controller
@RequestMapping("/test")
@Tag(name = "测试接口")
@Validated
public class TestController {@Autowiredprivate ArtifactService artifactService;@PostMapping("/v1/test")@Operation(summary  = "设置制品库权限")@NoPermissionpublic Result<Void> addArtifactPermission(@Validated @RequestBody AssetAuthDataDTO assetAuthData, @RequestHeader(value = "adminaction", defaultValue = "false") boolean adminAction) {return null;}@Operation(summary = "添加", description = "添加描述",security = { @SecurityRequirement(name = "sessionid")},responses = {@ApiResponse(description = "返回信息", content = @Content(mediaType = "application/json")),@ApiResponse(responseCode = "400", description = "返回400时候错误的原因")})@Parameters({@Parameter(name = "name", description = "名字", required = true),@Parameter(name = "typeId", description = "类型ID", required = true)})@PutMapping("add")@NoPermissionpublic Result<Void> add(String name, String typeId) {return null;}/*** 查询generic制品库下所有文件列表** @param quest 请求参数** @return** @author wangsb9* @data: 2023/4/6 14:54*/@ApiOperation(value = "查询generic制品库下所有文件列表", httpMethod = "GET")@GetMapping("/v1/generic/item/list")@ResponseBody@RepoKeyPermission(permission = "read", param = "quest.repoKey")public Result<GenericItemListVO> getGenericItemList(GetGenericItemListQuest quest) {if (ArtifactTypes.GENERIC.equalsIgnoreCase(BusinessUtils.getArtifactTypeFromRepoKey(quest.getRepoKey()))) {GenericItemListVO vo = artifactService.geGenericItemList(quest);return Result.success("获取当前generic制品库包含的制品成功", vo);} else {return Result.failed("请求路径非generic库路径");}}}

五、配置文件新增内容

application.yaml

springdoc:swagger-ui:# swagger-ui地址path: /swagger-ui/index.htmlenabled: true# 修复Failed to load remote configuration.
#    To configure, the path of a custom OpenAPI file . Will be ignored if urls is usedurl: /springdoc/api-docs
#  For custom path of the OpenAPI documentation in Json format.api-docs:path: /springdoc/api-docs
#  packages-to-scan: com.srdcloud.artifact.controller