springdoc-openapi使用

一、引入pom

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

二、新增配置类OpenApiConfig

@Configuration
public class OpenApiConfig {

    @Bean
    public 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;
    }


    @Bean
    public 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);

    }

    @Bean
    public 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 {

    @Autowired
    private ArtifactService artifactService;

    @PostMapping("/v1/test")
    @Operation(summary  = "设置制品库权限")
    @NoPermission
    public 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")
    @NoPermission
    public 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.html
    enabled: true
    # 修复Failed to load remote configuration.
#    To configure, the path of a custom OpenAPI file . Will be ignored if urls is used
    url: /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

六、验证

启动项目后访问地址http://<serviceIp>:<port>/swagger-ui/index.html

展示接口页面表示成功