/v3/api-docs inconsistence of operationId

[SleepyDeb]

Using the latest version (1.1.42) the api returns "flip-flopping" the operation id with "_1" as a suffix

First Time:

"operationId":"getUsers"

After:

"operationId":"getUsers_1"

Then:

"operationId":"getUsers"

and again

thanks in advance

[maciejkujawski]

It affects also other fields... With my schema openAPi.yaml at first generation is correct, when I refresh swagger or openApi url new file is wrong. Eg. First invocation:

     operationId: getFile
      parameters:
      - name: canonicalPath
        in: query
        description: xxx
        required: true
        schema:
          type: string
      responses:
        200:
          description: File resource
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/File'
        400:
          description: Wrong/malformed request parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

Second refresh:

     operationId: getFile_1
      parameters:
      - name: canonicalPath
        in: query
        description: xxx
        required: true
        schema:
          type: string
      responses:
        200:
          description: File resource
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/File'
        400:
          description: Wrong/malformed request parameters
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/File'
                - $ref: '#/components/schemas/Error'

On version 1.1.39 only changing operation id is affected. On newest 1.1.43 both error schema and operationId are wrong. Moreover the order of paths is different when I generate openApi.yaml/json with 1.1.39 vs 1.1.43

[springdoc]

Hi maciejkujawski,

The id operaration, generated dynamically should not have an impact on other fields.
Can you please add sample code to reproduce this behaviour.

[maciejkujawski]

You can reproduce it with:

  @Operation(description = "Download file")
  @ApiResponse(responseCode = "200", description = "File resource", content = @Content(schema = @Schema(implementation = java.io.File.class)))
  @ApiResponse(responseCode = "400", description = "Wrong request", content = @Content(schema = @Schema(implementation = java.lang.Error.class)))
  @ApiResponse(responseCode = "500", description = "Unexpected error", content = @Content(schema = @Schema(implementation = java.lang.Error.class)))
  @GetMapping(value = "/file",
      produces = MediaType.APPLICATION_JSON_VALUE)
  default ResponseEntity<java.io.File> getFile(
      @NotNull @Parameter(description = "File path", required = true) @Valid @RequestParam(value = "path") String path) {
    return ResponseEntity.status(HttpStatus.NOT_IMPLEMENTED).build();
  }

[SleepyDeb]

thx you guys i don't have time to demo this today :D

[maciejkujawski]

When it comes to "flip-flopping" operationId or changing order of paths maybe it's not critical but I am using your library to generate openAPI.yaml during tests and based on fact: the file changed or not we may generate some documentation + verify the external API was changed or not.

Btw: It is possible to force current implementation to preserve the operationId with annotation:

@Operation(operationId = "getFile", description = "Download file")

but I guess it's workaround ;-)

[maciejkujawski]

I guess swagger openapi Paths should be sorted before you return OpenAPI because Paths is based on LinkedList, so the order of iterating over Controllers affects the order of paths that are presented on openAPI.yaml. So it seems it might be somehow different between runs of application. I guess it affects also models.

[springdoc]

Hi,

The fix for this issue, will be available on v1.1.44 of springdoc-openapi.

[sujitmohanty30]

I guess swagger openapi Paths should be sorted before you return OpenAPI because Paths is based on LinkedList, so the order of iterating over Controllers affects the order of paths that are presented on openAPI.yaml. So it seems it might be somehow different between runs of application. I guess it affects also models.
@maciejkujawski
Hello Maciej,
i am new to use springdoc openapi,
I am facing this problem of having different sorting order each time i generates the openapi.json
Is there any way to sort the openapi paths ?
Thank you.

[dorongold]

Hi,

The fix for this issue, will be available on v1.1.44 of springdoc-openapi.

This issue does not seem to be fixed.
We are using SpringDoc version 1.4.4 and we just hit this issue after upgrading from Spring Boot 2.3.6 to Spring boot 2.4.5.
It looks like SpringDoc relies on the order of methods returned by org.springframework.web.servlet.handler.AbstractHandlerMethodMapping#getHandlerMethods which is non-deterministic.
After upgrading Spring Boot, and without any other changes, Operation IDs in the generated Swagger spec switch between themselves. For Example: getUser and getUser_1 switch, meaning each operation ID is given to the other operation, instead of to the same operation (as before the upgrade).

This causes our code, which uses clients generated by swagger-codegen, to break.

[bnasslahsen]

@maciejkujawski,

Please see the rules of Using GitHub Issues

You should be using the last stable version, before repoting any issue.
And if you feel you are still facing the issue, please provide a Minimal, Reproducible Example - with HelloController that reproduces the problem