Swagger и RESTful весенние ресурсы ненависти

В моем RESTful API все ресурсы расширяют базу ResourceSupport Spring, чтобы гарантировать Принципы по дизайну. Например:

public class PoolResource extends ResourceSupport {
    private String name;
    ...
}

Я также использую Swagger, и мне было интересно: можно ли как-то настроить swagger-ui, чтобы игнорировать свойства, поступающие от ResourceSupport?

введите здесь описание изображения

(Swagger-ui предоставляет приятный и простой интерфейс API. Одним из основных преимуществ использования Swagger является то, что API легко понять и использовать для тех, кто даже не знаком с REST API. , пока "ссылки" и "отношения" входят в картину.)


rest swagger swagger-ui spring-hateoas
person István Békési    schedule 21.01.2015    source источник
comment
Если вам не нужны гипермедиа, почему вы вообще используете Spring HATEOAS? Если вам нужна гипермедиа, почему вы используете Swagger (который активно подрывает гипермедиа)?   -  person Oliver Drotbohm    schedule 22.01.2015
comment
Я хочу гипермедиа. Изучив принципы RESTful, я понял преимущества использования гипермедиа, поэтому мне очень хотелось разработать уровень 3 API. Вот почему использование Spring HATEOAS. Но большинство пользователей API до сих пор не знают о гипермедиа, и не понимают, чем это вообще хорошо. Для них swagger предоставляет очень классное представление о полном API. Очень хорошо представить его кому угодно, и его легко понять даже от моей бабушки до старшего разработчика. Что вы имеете в виду, Swagger ниспровергает гипермедиа?   -  person István Békési    schedule 22.01.2015
comment
Большинство ответов предлагают мне не использовать чванство, слава REST решит большинство моих вопросов. Ладно, представим, я выбрасываю чванство. Это приводит меня к таким вопросам, как: - У меня есть ресурс Pool. Что делать, если у меня есть только что установленная система без какого-либо существующего экземпляра пула, поэтому я не могу ПОЛУЧИТЬ пул. Как создать (POST) пул чем? Как выглядит бассейн? - А как насчет необязательных полей? Валидации? Требуется... и т.д.? - А как насчет офлайн-документации?   -  person István Békési    schedule 26.01.2015
comment
Об этом упоминалось в этом сообщении блога blog.zenika.com/2013/07/11/ что чванство и ненависть дополняют друг друга. Swagger помогает нам документировать наши API, но ресурс по-прежнему должен предоставлять ссылки для навигации друг по другу.   -  person Ruelos Joel    schedule 12.05.2016
comment
Любой свет на это? У меня здесь аналогичная проблема > stackoverflow.com/questions/38694734/   -  person Manuel S.    schedule 01.08.2016
comment
Так вот, в чем тут вопрос?   -  person Stephane    schedule 13.12.2018

Ответы (6)


arrow_upward
8
arrow_downward

Я бы посоветовал отказаться от чванства и использовать restclient, например Postman . Postman делает ссылки, предоставляемые spring-hateoas, интерактивными, поэтому вы можете довольно быстро перемещаться по API. Если вы хотите предоставить дополнительную информацию/документацию, вы можете сохранить эти запросы в коллекции запросов в Postman и экспортировать ее для распространения. После того, как я попробовал несколько инструментов документирования для rest apis, включая raml, swagger, apiary и, наконец, Postman-коллекции в сочетании с hataos, я обнаружил, что последний меня больше всего устраивает.

person Thomas Eizinger    schedule 23.01.2015

arrow_upward
1
arrow_downward

С Spring Data REST 2.4.0.RELEASE теперь у вас есть несколько форм метаданных:

person gregturn    schedule 24.09.2015

arrow_upward
0
arrow_downward

Единственный разумный способ скрыть это - скрыть его от самой модели (есть несколько способов сделать это, хотя, если вы используете Spring MVC, я не уверен, что поддерживает swagger-springmvc).

Теоретически вы можете взломать swagger.js, чтобы скрыть это, но это целое приключение.

person Ron    schedule 21.01.2015

arrow_upward
0
arrow_downward

Spring RestDocs был создан с учетом гипермедиа. Он работает, чтобы обеспечить те же преимущества, что и чванство в области «сгенерированных документов», но не основан на URL.

http://docs.spring.io/spring-restdocs/docs/current/reference/html5/#getting-started-build-configuration

Стремится вывести что-то более похожее на документы github (Hyermedia'd).

https://developer.github.com/v3/#current-version

person tiny.dancer    schedule 11.06.2016

arrow_upward
0
arrow_downward

Кто-нибудь смотрел HAL Browser

http://api.opensupporter.org/hb2/browser.html#/api/v1

Он помогает визуализировать сеть отношений между ресурсами, поэтому не обязательно показывает примеры запросов для ресурса, но имеет области для отображения документации.

Я думаю, что это был бы более простой способ до некоторой степени документировать реализацию Hateos. И, возможно, одной из этих гипермедийных ссылок может быть веб-сайт чванства, или допустимые значения могут быть в документах, о которых я упоминал выше.

person brumScouse    schedule 11.12.2017

arrow_upward
0
arrow_downward

Не продлевайте ResourceSupport. Вместо этого для входной модели используйте POJO Pool, а для ответа используйте org.springframework.hateoas.Resource(s)<Pool>, который обертывает ваш POJO и позволяет определять ссылки.

person niebaraka    schedule 29.03.2019