Как я могу задокументировать объекты, на которые я не владею?

Question

Я возвращаю Page<SomeObject>В моем методе endpoints. В моем пользовательском интерфейсе OpenAPI, как я могу создать описание полей, которые поступают изorg.springframework.data.domain.Pageтип. Обычно я перехожу к объекту, который хочу задокументировать, и аннотирую его поля с помощью@Schema(description = "some description"). Но у меня нет доступа кPageкласс. Как я могу задокументировать его поля?

Вероятно, мне здесь не хватает чего-то простого, но любая помощь будет принята с благодарностью.

PS: я использую OpenAPI v3 и springdoc

Answer 1

Вы можете использовать OpenApiCustomiser.

Скажем, например, у вас есть этот контроллер:

@RestController общедоступный класс HelloController {

@GetMapping("/hello")
Page<PersonDTO> getPage() {
    return null;
}

}

Предположим, вы хотите добавить описание элемента Pageable:

@Bean
public OpenApiCustomiser pageableOpenApiCustomiser() {
    return openApi -> {
        Schema pageableSchema = openApi.getComponents().getSchemas().get("Pageable");
        pageableSchema.setDescription("my description");
    };
}

Та же самая логика применима к любому другому атрибуту, который вы настроили.