Springdoc random api-docs generation

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

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...

one other flag mentioned here:

springdoc:
 writer-with-order-by-keys