Limitations of OpenAPI descriptions

[martinfkaeser]

There are two known issues with the OpenAPI/SpringDoc descriptions:

1. Generic classes can't get specific schema descriptions depending on the type parameter via SpringDoc annotations. Example: TypeKeyNameVerboseDto<CountryCode> The spec only shows the generic description that is annoted on TypeKeyNameVerboseDto, although a specific schema TypeKeyNameVerboseDtoCountryCode is generated.

2. There is an OpenAPI limitations not allowing to specify a field description for singular objects of complex type (contrary to collection objects of complex type and objects of primitive type), see https://github.com/springdoc/springdoc-openapi/issues/1178 . There is only schema description of the referred type. Example: legalAddress in LegalEntityPartnerCreateRequest etc.

[martinfkaeser]

There is the potential workaround to programmatically modify schema descriptions and create schema aliases: https://github.com/springdoc/springdoc-openapi/issues/685

I tried this out in https://github.com/eclipse-tractusx/bpdm/pull/405

But we decided not to go with it because it has still too many downsides:

• Descriptions need to be maintained in OpenApiConfig, not in the DTOs.
• Field descriptions are just not supported in OpenAPI, using schema descriptions for that is a poor workaround. This would result in many nearly identical schemas only differing in the description, e.g. legalAddressAliasForLogisticAddressDto and legalAddressAliasForLogisticAddressVerboseDto.
• Very hard to maintain.