@BeanParam not documented when annotated with @Parameter

Question

I'm trying to document my api using the swagger-maven-plugin.

When I annotate a route param with @Parameter, it's well documented in the openapi generated file as long as it's not annotated with @BeanParam.

As stated in the swagger core documentation,

The @Parameter can be used in place of or together with the JAX-RS parameter annotations (@PathParam, @QueryParam, @HeaderParam, @FormParam and @BeanParam). While swagger-core / swagger-jaxrs2 scan these annotations by default, the @Parameter allows to define more details for the parameter.

How can I get my @BeanParam parameters documented in my openapi file?

Here is my pom.xml:

<dependencies>
    <dependency>
        <groupId>io.swagger.core.v3</groupId>
        <artifactId>swagger-jaxrs2</artifactId>
        <version>2.1.1</version>
    </dependency>
</dependencies>

<build>
    <plugins>
        <plugin>
            <groupId>io.swagger.core.v3</groupId>
            <artifactId>swagger-maven-plugin</artifactId>
            <version>2.1.1</version>
            <configuration>
                <outputFileName>openapi</outputFileName>
                <outputPath>target/doc</outputPath>
                <outputFormat>YAML</outputFormat>
                <resourcePackages>...</resourcePackages>
                <readAllResources>false</readAllResources>
            </configuration>
            <executions>
                <execution>
                    <phase>generate-resources</phase>
                    <goals>
                        <goal>resolve</goal>
                    </goals>
                </execution>
            </executions>
        </plugin>
    </plugins>
</build>

And here my annotated api:

@GET
@Path("/authorize")
@Operation(summary = "Summary", description = "Description")
Response authorize(
        // Parameter doesn't show up in generated documentation
        @Parameter(
                description = "Request",
                name = "request",
                required = true
        )
        @BeanParam Oauth2AuthorizationRequest request,
        // Parameter shows up correctly in generated documentation
        @Parameter(
                description = "Session id",
                name = "sessionId",
                required = true
        )
        @CookieParam("sessionId") String sessionId
);

The generated file is:

openapi: 3.0.1
paths:
  /auth/oauth2/authorize:
    get:
      summary: Summary
      description: Description
      operationId: authorize
      parameters:
      - name: sessionId
        in: cookie
        description: Session id
        required: true
        schema:
          type: string

Baboo · Accepted Answer · 2020-02-27 20:14:30Z

2

After some trials I managed to document my @BeanParam in the openapi file. Annotations have to be put inside of the class annotated @BeanParam like this:

public class Oauth2AuthorizationRequest {
    // Use the @Parameter annotation to document the attribute.
    @HeaderParam("Authorization")
    @Parameter(description = "Authorization header")
    String authorization;

    // If the attribute is a @FormParam, use the @Schema annotation.
    @FormParam("client_id")
    @Schema(description = "The id of the client")
    String client_id;

    // If the attribute is a @FormParam and is required, 
    // use the @Schema annotation for the description
    // and the @Parameter one to set it as required.
    @FormParam("grant_type")
    @Schema(description = "Should be either \"credentials\" or \"password\"")
    @Parameter(required = true)
    String grant_type;
}

And the endpoint is simplified as such:

@GET
@Path("/authorize")
@Operation(summary = "Summary", description = "Description")
Response authorize(
    // No more annotation on the @BeanParam
    @BeanParam Oauth2AuthorizationRequest request,
    @Parameter(
        description = "Session id",
        name = "sessionId",
        required = true
    )
    @CookieParam("sessionId") String sessionId
);

answered Feb 27, 2020 at 20:14

Baboo

4,3184 gold badges24 silver badges41 bronze badges

Sign up to request clarification or add additional context in comments.

5 Comments

bobK Over a year ago

Can it be down the other way around? Have an openapi yml file generate an interface with a beanparam?

Baboo Over a year ago

Have a look at swagger codegen. I haven't tested it but looks like what you're looking for.

bobK Over a year ago

I know it. I just haven't found a way to generate an interface with @beanparam instead of separate parameters

YevgenyL Over a year ago

@Baboo_ Did you understand why only in case of BeanParam need to annotate the object's (Oauth2AuthorizationRequest) params by ourselves with swagger annotations? I mean if it wasn't BeanParam, then swagger will read the validation annotations automatically, and so you could use NotNull annotation instead of Parameter(requires = true) that you used.

Baboo Over a year ago

I'm not really sure why. A BeanParam is a group of Parameters and I think swagger makes a distinction with simple parameters. If you find out why I'm curious to know

Collectives™ on Stack Overflow

@BeanParam not documented when annotated with @Parameter

1 Answer 1

5 Comments

Your Answer

Hot Network Questions

Collectives™ on Stack Overflow

1 Answer 1

5 Comments

Your Answer

Sign up or log in

Post as a guest

Related