Springdoc-OpenAPI with path parameters and command object

Question

I am getting validation errors in my Springdoc generated OpenAPI spec and can't see to find an example online that matches how my Java code is formed.

I am trying to generate an OpenAPI spec with Springdoc for a Spring Boot controller. I have a mapping for a path that has multiple path variables and the method signature accepts a command object (the command object is automatically constructed from these path variables). Swagger-UI.html seems to work more or less but the generated JSON/YAML spec does not appear to be valid.

Code snippet I'm referring to:

@GetMapping("/myPath/{foo}/{bar}/{baz}")
public Mono<MyServiceResponse> doSomethingInteresting(@Valid DoSomethingInterestingCommand command) {
    return interestingService.doSomethingInteresting(command);
}

The OpenApi snippet this generates is:

paths:
  '/myPath/{foo}/{bar}/{baz}':
    get:
      tags:
        - my-controller
      operationId: doSomethingInteresting
      parameters:
        - name: command
          in: query
          required: true
          schema:
            $ref: '#/components/schemas/DoSomethingInterestingCommand'

This then yields errors such as this:

Semantic error at paths./myPath/{foo}/{bar}/{baz}
Declared path parameter "foo" needs to be defined as a path parameter at either the path or operation level

What should I do differently in order to get the generated spec to be well-formed? I am also curious as to why the swagger-ui.html page seems to be working OK, but that is less critical.

I think will be a better idea to raise an issue at github.com/springdoc/springdoc-openapi/issues — Debargha Roy

brianbro brianbro · Accepted Answer · 2021-05-23T16:44:55

To generate the correct openAPI spec, you can add the swagger-annotations.

@Parameter(in = ParameterIn.PATH, name ="foo" ,schema = @Schema(type = "string"))
@Parameter(in = ParameterIn.PATH, name ="bar" ,schema = @Schema(type = "string"))
@Parameter(in = ParameterIn.PATH, name ="baz" ,schema = @Schema(type = "string"))
@GetMapping("/myPath/{foo}/{bar}/{baz}")
public Mono<MyServiceResponse> doSomethingInteresting(@Valid @Parameter(hidden = true) DoSomethingInterestingCommand command) {
    return interestingService.doSomethingInteresting(command);
}

Springdoc-OpenAPI with path parameters and command object

1 Answers