使用开放 API 配置的全局参数集？

Posted 2023-03-10

【中文标题】使用开放 API 配置的全局参数集？

【英文标题】：Global Parameter set using Open API configurations?

【发布时间】：2020-05-17 07:21:02

【问题描述】：

我正在使用Spring Boot REST OpenAPI 3 规范。在此示例中，我希望在向每个端点发出请求时全局设置要传递的标头 (Custom-Header-Version=v1)。

现在的问题是我有 100 个 REST 端点，对于每个端点，我需要继续添加 @Parameter(in = ParameterIn.HEADER .....，这个配置，而不是我希望在全局范围内设置它。如果我们可以在 OpenAPI 中做到这一点，有什么办法吗？

有没有办法从 Spring doc ui 中删除 SmartBear 标志？

@RestController
@RequestMapping("/api")
@Tag(name = "contact", description = "the Contact API")
public class HelloController 

    @Operation(summary = "Find Contacts by name", description = "Name search by %name% format", tags = "contact")
    @ApiResponses(value = 
            @ApiResponse(responseCode = "200", description = "successful operation", content = @Content(array = @ArraySchema(schema = @Schema(implementation = PersonDTO.class)))))
    @Parameter(in = ParameterIn.HEADER, description = "Custom Header To be Pass", name = "Accept-version"
            , content = @Content(schema = @Schema(type = "string", defaultValue = "v1", allowableValues = "v1", implementation = PersonDTO.class)))
    @GetMapping(value = "/contacts", headers = "Custom-Header-Version=v1")
    public ResponseEntity<List<PersonDTO>> findAll(
            @Parameter(description = "Page number, default is 1") @RequestParam(value = "page", defaultValue = "1") int pageNumber,
            @Parameter(description = "Name of the contact for search.") @RequestParam(required = false) String name) 

            return null;
        

【参考方案1】：

你可以试试下面的代码。在ouled saber上面提到的代码中添加了.example("v1")

@Component
public class GlobalHeaderOperationCustomizer implements OperationCustomizer 
    @Override
    public Operation customize(Operation operation, HandlerMethod handlerMethod) 

        Parameter customHeaderVersion = new Parameter().in(ParameterIn.HEADER.toString()).name("Custom-Header-Version")
                .description("Custom Header Version)").schema(new StringSchema()).example("v1").required(false);

        operation.addParametersItem(customHeaderVersion);       
        return operation;
    

我有同样的要求，我大摇大摆地像下面这样

Image from swagger ui

【参考方案2】：

您可以只定义一个 OperationCustomizer。

@Component
public class GlobalHeaderOperationCustomizer implements OperationCustomizer 
    @Override
    public Operation customize(Operation operation, HandlerMethod handlerMethod) 
        Parameter parameterHeader = new Parameter()
                .in(ParameterIn.HEADER.toString())
                .schema(new StringSchema().addEnumItem("v1")._default("v1").name("Accept-version"))
                .description("Custom Header To be Pass");;
        operation.addParametersItem(parameterHeader);
        return operation;
    

【讨论】：

使用此代码，我看不到默认值正常工作，它没有默认值。

能否回复以上评论？

这么久未决，能否请您在此回复？