注释中的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;
}

我知道我可以生成约束描述(snippets)，但它只为验证注释生成描述。

我在找像斯威格的https://github.com/swagger-api/swagger-core/wiki/Annotations#apimodelproperty一样的东西。

Answer 1

我是REST Docs项目的负责人，我认为注释不是编写文档的好方法。如果您不同意这个观点，并且希望使用注释，您可以编写一个类似于约束描述所做的附加内容。您可以传递一个类来内省并自动生成FieldDescriptor实例，然后可以传递到请求和响应字段片段中。

Answer 2

我们构建了Spring的扩展，允许使用Javadoc作为字段描述：

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

但目前，只有在使用杰克逊和MockMvc测试时，这才能奏效。

项目：https://github.com/ScaCap/spring-auto-restdocs

导论：https://dzone.com/articles/introducing-spring-auto-rest-docs