springdoc / springdoc-openapi

Library for OpenAPI 3 with spring-boot

Home Page:https://springdoc.org

Geek Repo:Geek Repo

Github PK Tool:Github PK Tool

`@Schema` annotation not picked up when used on another annotation.

Jardo-51 opened this issue · comments

Describe the bug

I created a minimal reproducible example with the latest version of Spring Boot (3.3.0) and springdoc-openapi-starter-webflux-ui (2.5.0).

Let's say I have a large number of endpoints which use parameter personId. I want to document that parameter, but I don't want to copy-paste the doc annotations everywhere. So I created the following annotation:

@Retention(RetentionPolicy.RUNTIME)
@Parameter(description = "Person identifier", example = "1234")
public @interface PersonIdParam {

}

I use the annotation in the following way:

@GetMapping("/person/{id}")
public Mono<PersonDto> getById(@PathVariable @PersonIdParam String id) {
	...
}

This works fine, the description and example is added to every parameter in the generated docs.

But now, I would like to do the same thing for object fields. I created the following annotation:

@Target(ElementType.FIELD)
@Retention(RetentionPolicy.RUNTIME)
@Schema(description = "Person identifier", example = "1234")
public @interface PersonIdField {

}

And I use it like this:

public class PersonDto {

	@PersonIdField
	private String id;

	...
}

But this doesn't work. The description and example are not added to the generated docs.

To Reproduce
Steps to reproduce the behavior:

Screenshot from 2024-06-05 11-37-53

Expected behavior

  • Field PersonDto.id has description and example value.