Duplicated parameters in OpenAPI documentation

Question

I'm just starting out with OpenAPI and learning about the different annotations in version 3.0 using Javadoc, as I haven't found any posts specifically about them.

If I use the parameters parameter in the @Operation annotation, the generated documentation duplicates the parameters, that is, it displays the parameters described in parameters and in the RESTful method signatures.

Personally, I prefer using parameters to better organize the code. So, I ask: is it possible to configure something in somewhere to use the parameters parameter in the @Operation annotation?

Here is my configuration in the pom.xml file:

<!-- https://mvnrepository.com/artifact/io.swagger.core.v3/swagger-annotations-jakarta -->
<dependency> 
   <groupId>io.swagger.core.v3</groupId> 
   <artifactId>swagger-annotations-jakarta</artifactId> 
   <version>${io.swagger.core.v3.version}</version>
</dependency>
<!-- https://mvnrepository.com/artifact/io.swagger.core.v3/swagger-jaxrs2-jakarta -->
<dependency> 
   <groupId>io.swagger.core.v3</groupId> 
   <artifactId>swagger-jaxrs2-jakarta</artifactId> 
   <version>${io.swagger.core.v3.version}</version>
</dependency>
<!-- https://mvnrepository.com/artifact/io.swagger.core.v3/swagger-jaxrs2-servlet-initializer-jakarta -->
<dependency> 
   <groupId>io.swagger.core.v3</groupId> 
   <artifactId>swagger-jaxrs2-servlet-initializer-jakarta</artifactId> 
   <version>${io.swagger.core.v3.version}</version>
</dependency>

Here's a sample of both: #1 Using parameters in @Operation annotation:

   @Operation(
      summary="Get some data",
      description="Get all data available",
      parameters= {
         @Parameter(
            name="issuer",
            description="Doc issuer",
            required=true,
            example="1",
            in=ParameterIn.PATH,
            allowEmptyValue=false,
            schema=@Schema(
               type="integer",
               implementation=Integer.class,
               pattern="\\d+"
            )
         )
      },
      responses={
         @ApiResponse(responseCode="200",
                      description="All available data",
                      content={
                         @Content(mediaType=MediaType.APPLICATION_JSON),
                         @Content(mediaType=MediaType.APPLICATION_XML)
                      }
                     )
      }
   )
   @GET @Path("issuer/{issuer:\\d+}")
   public Response findByIssuer(@PathParam("issuer") Integer issuer) {
      ...
   }

#2 Using @Parameter in method signature:

   @Operation(
      summary="Get some data",
      description="Get all data available",
      responses={
         @ApiResponse(responseCode="200",
                      description="All available data",
                      content={
                         @Content(mediaType=MediaType.APPLICATION_JSON),
                         @Content(mediaType=MediaType.APPLICATION_XML)
                      }
                     )
      }
   )
   @GET @Path("issuer/{issuer:\\d+}")
   public Response findByIssuer(
                   @Parameter(name="issuer",
                              description="Get all data available"
                   )
                   @PathParam("issuer") Integer issuer) {
      ...
   }

When I use #1: Services documentation shows issuer duplicated; #2: Services documentation shows issuer just once.

This is an example with just one parameter (@PathParam), but with methods with a few more parameters (@PathParam / @QueryParam) #2 gets messy and I'd like to use #1 but I don't know if it's possible and, if it is, which configuration I should apply and where.

Can you post a sample method declaration with annotations that results in duplicated parameters? — Helen
– Helen, Commented Oct 16 at 17:59
I think the correct parameter annotations are @PathParam / @QueryParam / @Parameter / etc. not parameters; see the docs. — Helen
– Helen, Commented Oct 16 at 17:59

Jeremy Fiel · Accepted Answer · 2025-10-16 20:03:03Z

You can define parameters at the Operation or the Method, but they will be duplicated if you define both.

OpenAPI allows parameter definitions for a group of operations at the PathItemObject level or for an individual operation at the OperationObject


@GET
@Consumes("application/json")
@Path("/issuers/{issuer-id}")
@Operation(
    summary= "My api",
    responses = {
        @ApiResponse(
          responseCode = "200",
          description = "OK",
          content = @Content(
            schema = @Schema(implementation = Issuer.class)
          )
        )    
    }
)
@DELETE
@Consumes("application/json")
@Path("/issuers/{issuer-id}")
@Operation(
    summary= "My api",
    responses = {
        @ApiResponse(
          responseCode = "204",
          description = "No Content"
        )
    }
)
@Parameter(
    name = "issuer-id",
    description = "an issuer identifier", 
    in = "path",
    required = true,
    schema = @Schema(type = "string")
)

openapi: 3.0.4
info:
  title: my api
  version: v1
paths:
  '/issuers/{issuer-id}':
    parameters: # <  at the path item level, covers all operations defined (GET, POST, PUT, DELETE)
    - name: issuer-id
      in: path
      required: true
      schema:
        type: string
    get:
      summary: my api
      responses:
        '200':
          description: OK
          content:
            'application/json':
              schema:
                properties:
                  issuerID: 123
                  issuerName: test
    delete:
      summary: my api
      responses:
        '204':
          description: OK


@GET
@Consumes("application/json")
@Path("/issuers/{issuer-id}")
@Operation(
    summary= "My api",
    parameters = {
      @Parameter(
        name = "issuer-id",
        description = "an issuer identifier",
        in = "path",
        required = true,
        schema = @Schema(type = "string")
      )
   },
    responses = {
        @ApiResponse(
          responseCode = "200",
          description = "OK",
          content = @Content(
            schema = @Schema(implementation = Issuer.class)
          )
        )
    }
)

openapi: 3.0.4
info:
  title: my api
  version: v1
paths:
  '/issuers/{issuer-id}':
    get:
      summary: my api
      parameters: # <  at the individual operation level, only applies to the GET operation of this url
    - name: issuer-id
      in: path
      required: true
      schema:
        type: string
      responses:
        '200':
          description: OK
          content:
            'application/json':
              schema:
                properties:
                  issuerID: 123
                  issuerName: test

Collectives™ on Stack Overflow

Duplicated parameters in OpenAPI documentation

1 Answer 1

Comments

Your Answer

Hot Network Questions

Collectives™ on Stack Overflow

1 Answer 1

Comments

Your Answer

Sign up or log in

Post as a guest

Related