The API documentation is based on a JSON automatically generated by CXF and presented through a frontend by Swagger. When developing an API, one must use the Swagger provided annotations to document entities and services, the library will then take care of the OpenAPI based document generation.
Every API must have a @Tag annotation that describes the content and purpose of the API.
Every API operation must be annotated via a @Operation annotation, which allows to specify a summary and a detailed description of the operation itself. A second annotation is needed to correctly document an operation: @ApiResponse. This annotation allows the developer to specify a set of possible responses that can occur when a client calls that specific operation of the API. The annotation can be repeated as many times as the possible responses and each of them must be correctly and completely documented via the @ApiResponse annotation. This annotation allows to specify: the HTTP response code that will be returned (responseCode), an extensive description of the operation (description), eventually the additional headers or custom headers for the operation (headers), and if needed, the content of the response when it presents additional data (content).
Every DTO must have its own @Schema annotation defining its name and an exhaustive description of the purpose of the object. Inside a DTO, every non-self-explaining field should be annotated with its @Schema annotation with the same data: name and description. Every field must also be annotated with a @JsonProperty annotation that can be used to change the property name, differentiating it from the actual Java variable definition. Please note that the @JsonProperty annotation is also used in BusinessObjects to explicit the database object to which a variable corresponds to.
The annotations not only serve a documentational purpose, but they are also used to define constraints on fields. For example, when implementing a DTO the @NotNull annotation can be used to require that a certain field must be populated by the client. This type of validation must be activated via the @Valid annotation put on the operation parameter for the body of POST, PATCH, and PUT verbs. The GET verb parameters have their validation activated by default, in fact, QueryString and QueryParameter have their validation active by default, whichever verb they are on.