SpringDoc OpenAPI 1.x版本中Schema描述的引用问题解析

在使用SpringDoc OpenAPI 1.7.0版本时，开发者遇到了一个关于Schema描述在引用对象中无法正确显示的问题。本文将深入分析这个问题及其解决方案。

问题背景

在OpenAPI 3.1.0规范中，允许在引用对象($ref)旁边添加描述字段(description)，这是一个非常有用的特性。然而，当开发者尝试在SpringDoc OpenAPI 1.7.0版本中使用这个特性时，发现描述字段没有被正确生成。

问题重现

开发者在一个Pet类中为两个Category类型的字段添加了Schema注解和描述：

@JsonProperty("category")
@JacksonXmlProperty(localName = "category")
@Schema(description = "category description")
private Category category;

@JsonProperty("otherCategory")
@JacksonXmlProperty(localName = "otherCategory")
@Schema(description = "otherCategory description")
private Category otherCategory;

期望生成的OpenAPI文档应该包含描述信息：

category:
    $ref: '#/components/schemas/Category'
    description: 'category description'
otherCategory:
    $ref: '#/components/schemas/Category'
    description: 'otherCategory description'

但实际生成的文档中缺少了description字段：

category:
  $ref: '#/components/schemas/Category'
otherCategory:
  $ref: '#/components/schemas/Category'

解决方案

经过验证，这个问题在SpringDoc OpenAPI 2.3.0版本中已经得到解决。对于仍在使用1.x版本的用户，官方建议升级到1.8.0版本，这是支持Spring Boot 2.x和1.x的最新开源版本。

版本选择建议

对于需要长期支持的组织，可以考虑SpringDoc提供的扩展支持服务。对于大多数开发者来说，如果项目允许，建议升级到2.x版本以获得更好的功能和更完善的支持。

总结

Schema描述在引用对象中的显示问题是一个常见的API文档生成挑战。通过选择合适的SpringDoc OpenAPI版本，开发者可以确保API文档的完整性和准确性。对于仍在使用1.x版本的项目，升级到1.8.0版本是解决这个问题的推荐方案。