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.

• Helen: Can you post a sample method declaration with annotations that results in duplicated parameters?
• Helen: I think the correct parameter annotations are @PathParam / @QueryParam / @Parameter / etc. not parameters; see the docs.

Answer 1

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