Генерация случайных API-документов Springdoc

Я хочу создать api, который принимает другой тип контента.

Проблема, с которой я столкнулся, заключается в том, что если я несколько раз запускаю свое приложение, у меня будет другая выходная документация.

@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();
    }
}

В настоящее время он генерирует неправильные 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"
    }
},

Если я перезапущу свой сервер без изменения кода, будет сгенерирован следующий ответ

"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"
    }
},

Я ожидал, что перезапуск моего сервера всегда будет генерировать ту же документацию.


java springdoc
person roll    schedule 10.08.2020    source источник

Ответы (1)


arrow_upward
1
arrow_downward

Вы смотрели документацию?

Вы можете использовать свойства swagger-ui, не переопределяя стандартный способ сортировки (operationsSorter и tagsSorter).

Например:

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

Если вам нужен порядок на стороне сервера, вы можете использовать OpenApiCustomiser для сортировки элементов

Это пример кода, который вы можете настроить с помощью компараторов в зависимости от желаемой логики сортировки:

Пример для сортировки схем в алфавитном порядке:

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

Пример сортировки тегов в алфавитном порядке:

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

Вы можете полностью контролировать порядок элементов и сортировать их в зависимости от вашего варианта использования ...

person Community    schedule 11.08.2020
comment
Я отредактирую свой вопрос, чтобы он был более конкретным, но моя проблема в том, что порядок метода в моем классе меняет форму (не только порядок) документации, некоторые части отсутствуют. - person roll; 11.08.2020