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;
}

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

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

Answer 1

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