Springdoc random api-docs generation

Question

I am looking to generate an api that take different content type.

The problem I am facing is that if I run several time my application I have different output documentation

@RestController
public class MyRestController {

    @Operation(summary = "GetMyData", operationId = "gettt",
        responses = @ApiResponse(responseCode = "204", content = @Content(mediaType = "application/vnd.something")))
    @GetMapping(produces = "application/vnd.something")
    public ResponseEntity<Void> getSomethingElse() {
        return noContent().build();
    }

    @GetMapping(produces = TEXT_PLAIN_VALUE)
    public String get() {
        return "some text";
    }

    @GetMapping(produces = HAL_JSON_VALUE)
    public EntityModel<JsonResponse> getHal() {
        return EntityModel.of(new JsonResponse(),
            linkTo(MyRestController.class).slash("somelink").withSelfRel()
        );
    }

    @GetMapping(produces = APPLICATION_JSON_VALUE)
    public JsonResponse getJson() {
        return new JsonResponse();
    }
}

It currently generate a wrong api-docs

"operationId": "gettt_1_1_1",
"responses": {
    "200": {
        "content": {
            "application/hal+json": {
                "schema": {
                    "$ref": "#/components/schemas/EntityModelJsonResponse"
                }
            },
            "application/json": {
                "schema": {
                    "$ref": "#/components/schemas/JsonResponse"
                }
            },
            "text/plain": {
                "schema": {
                    "type": "string"
                }
            }
        },
        "description": "OK"
    },
    "204": {
        "content": {
            "application/hal+json": {
                "schema": {
                    "$ref": "#/components/schemas/EntityModelJsonResponse"
                }
            },
            "application/vnd.something": {},
            "text/plain": {
                "schema": {
                    "type": "string"
                }
            }
        },
        "description": "No Content"
    }
},

If I restart my server without changing the code the following response is generated

"operationId": "gettt_1",
"responses": {
    "200": {
        "content": {
            "application/hal+json": {
                "schema": {
                    "$ref": "#/components/schemas/EntityModelJsonResponse"
                }
            },
            "application/json": {
                "schema": {
                    "$ref": "#/components/schemas/JsonResponse"
                }
            },
            "text/plain": {
                "schema": {
                    "type": "string"
                }
            }
        },
        "description": "OK"
    },
    "204": {
        "content": {
            "application/vnd.something": {}
        },
        "description": "No Content"
    }
},

I would expect that restarting my server will always generate the same documentation

Answer 1

Have you looked at the documentation?

• https://springdoc.github.io/springdoc-openapi-demos/springdoc-properties.html#swagger-ui-properties

You can use the swagger-ui properties, without having to override the standard way of sorting (operationsSorter and tagsSorter).

For example:

springdoc.swagger-ui.operationsSorter=method
springdoc.swagger-ui.tagsSorter=alpha

If you want a an order on the server side, you can use OpenApiCustomiser, to sort the elements

This is a sample code that you can customize using Comparators, depending on the sorting logic you want:

Example, for alphabetical order sorting of schemas:

@Bean
public OpenApiCustomiser sortSchemasAlphabetically() {
    return openApi -> {
        Map<String, Schema> schemas = openApi.getComponents().getSchemas();
        openApi.getComponents().setSchemas(new TreeMap<>(schemas));
    };
}

Example for sorting tags, in alphabetical order:

@Bean
public OpenApiCustomiser sortTagsAlphabetically() {
    return openApi -> openApi.setTags(openApi.getTags()
            .stream()
            .sorted(Comparator.comparing(tag -> StringUtils.stripAccents(tag.getName())))
            .collect(Collectors.toList()));
}

You can have full control on the elements order, and you can sort them depending on your use case...

Answer 2

one other flag mentioned here :

springdoc:
 writer-with-order-by-keys