Описание поля Spring-restdocs из аннотаций

Можно ли использовать аннотации (на уровне поля) для описания полей?

Я знаю, что могу использовать 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.


spring-restdocs spring-auto-restdocs
person Bartosz Bilicki    schedule 07.12.2016    source источник

Ответы (2)


arrow_upward
5
arrow_downward

Это не так. Я руководитель проекта REST Docs и считаю, что аннотации - не лучший способ писать документацию. Если вы не согласны с этим мнением и хотите использовать аннотации, вы можете написать надстройку, аналогичную тому, что делается на основе описаний ограничений. Вы можете передать ему класс для самоанализа и автоматически генерировать FieldDescriptor экземпляры, которые затем можно передать в фрагменты полей запроса и ответа.

person Andy Wilkinson    schedule 07.12.2016
comment
Просто для интереса, не могли бы вы вкратце объяснить, почему вы считаете аннотации для документации плохой практикой? - person aboger; 11.12.2019
comment
Написать хорошую документацию сложно. Атрибут аннотации в вашей среде IDE - не идеальная среда для написания, поэтому они только усложняют задачу. По моему опыту, использование Asciidoc в текстовом редакторе приятнее и продуктивнее. Кроме того, расположение этих аннотаций, например, на контроллере Spring MVC, на несколько шагов удалено из HTTP-запросов и ответов, которые волнуют кого-то, использующего ваш RESTful API. Я думаю, что написание документации на уровне HTTP значительно увеличивает шансы на точность. - person Andy Wilkinson; 11.12.2019

arrow_upward
5
arrow_downward

Мы создали расширение для 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/introduction-spring-auto-rest-docs

person Florian Benz    schedule 20.02.2017