Spring-restdocs 字段描述来自注解

Question

是否可以使用注释（在字段级别）为字段提供描述？

我知道我可以使用 description 方法

.andDo(document("index", responseFields( 
            fieldWithPath("contact").description("The user's contact details"),

但我更愿意将该描述与字段定义放在我的响应对象中。

class IndexResponse {
 //The user's contact details
 String contract;
}

Answer 1

没有。我是 REST Docs 项目的负责人，我认为注释不是编写文档的好方法。如果您不同意该意见并想使用注释，您可以编写一个类似于约束描述所做的附加组件。您可以将其传递给 class 以自省并自动生成 FieldDescriptor 实例，然后您可以将这些实例传递到请求和响应字段片段中。

Answer 2

我们构建了 Spring REST 文档的扩展，允许使用 Javadoc 进行字段描述：

class IndexResponse {
  /**
   * The user's contact details
   */
  String contract;
}

但目前这仅在使用 Jackson 和 MockMvc 测试时有效。

Spring-restdocs field description from annotations