2

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

我知道我可以使用description方法

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

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

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

我知道我可以生成约束描述（http://docs.spring.io/spring-restdocs/docs/current/reference/html5/#_using_constraint_descriptions_in_generated_snippets），但它只为验证注释生成描述。

我正在寻找来自 Swagger的类似https://github.com/swagger-api/swagger-core/wiki/Annotations#apimodelproperty的东西。

4

2 回答 2

5

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

于 2016-12-07T15:33:26.730 回答
5

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

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

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

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

一篇介绍文章：https ://dzone.com/articles/introducing-spring-auto-rest-docs

于 2017-02-20T22:12:20.723 回答