注释中的 Spring-restdocs 字段描述答案

【问题标题】：Spring-restdocs field description from annotations注释中的 Spring-restdocs 字段描述
【发布时间】：2016-12-07 14:41:14
【问题描述】：

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

我知道我可以为此使用description 方法

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

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

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

【问题讨论】：

【解决方案1】：

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

【讨论】：

只是出于兴趣，能否请您简要解释一下为什么您认为将注释作为文档不好的做法？
编写好的文档很难。 IDE 中注释的属性不是理想的编写环境，因此它们只会使困难的事情变得更难。根据我的经验，在文本编辑器中使用 Asciidoc 会更愉快、更高效。此外，这些注释的位置，例如在 Spring MVC 控制器上，是从使用 RESTful API 的人关心的 HTTP 请求和响应中删除的几个步骤。我认为在 HTTP 级别编写文档会大大增加它准确的机会。

【解决方案2】：

我们为 Spring REST Docs 构建了一个扩展，允许使用 Javadoc 进行字段描述：

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

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

【讨论】：