Описание поля 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, и я считаю, что аннотации не являются хорошим способом написания документации. Если вы не согласны с этим мнением и хотите использовать аннотации, вы можете написать надстройку, подобное тому, что сделано из описаний ограничений. Вы можете передать ему класс для интроспекции и автоматического генерации экземпляров FieldDescriptor, которые затем можно передать в фрагменты поля запроса и ответа.

Answer 2

Мы построили пристройку к Spring REST Docs, что позволяет с помощью 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