Я использую Swagger для моего API-интерфейса ASP.NET с помощью Swashbuckle, который описывает мой API в отдельном документе и предоставляет хороший пользовательский интерфейс для всей этой информации.Должны ли вы объединить Swagger с HATEOAS/HAL/JSON-LD?
Есть ли какие-либо преимущества использования чего-то типа HATEOAS, HAL или JSON-LD, которые изменяют сам документ в сочетании с Swagger?
Here является примером того, кто использует Swagger с HAL.
Как и сампада, как оба - чванство и HATEOAS - добавляет больше значения в разные размеры вашего апи.
Кураж добавит ценности жизненного цикла разработки, что делает ваш апи более понятным и доступным для просмотра во время разработки.
HATEOAS добавит значение к вашему API, когда используется клиентами. Ссылки, предоставленные HATEOAS, дают вам возможность связать различные части (то есть: ресурсы) вашего api, не требуя жесткого кодирования этих ссылок в коде клиента вашего приложения.
Предполагая, что у вас есть договор с несколькими документами, относящимися к нему. Один довольно распространенный способ смоделировать это было бы с помощью двух ресурсов: Resource
Чтобы связать эти два вместе вы можете добавить поля в обеих моделях ресурсов, содержащих массивы соответствующего ресурса. Кроме того, вы должны реализовать эти неявные знания в своем клиентском приложении. Таким образом, вы будете добавлять беспорядок в свои представления ресурсов с течением времени, загрязняя его информацией об отношениях с другими объектами.
В этом случае HATEOAS вступает в игру, перемещая информацию об этих объектах из ваших бизнес-объектов и предоставляя единый способ справиться с этими отношениями. Оба ресурса бизнес-объектов теперь будут включать один стандартизованный заголовок или поле значения, содержащее информацию о all отношения текущего ресурса. . Один контрактный ресурс теперь будет иметь 3 ссылки с rel-attribute «document», связывающие с соответствующими ресурсами документа и 1 ссылку с rel-attribute «order», связывающую с порядком, в результате которого был заключен этот контракт.
Насколько я знаю JSON-LD используется для нормализации лексики различных интерфейсов, что делает его легче использовать их бок о бок. Некоторые могут использовать firstName & lastName как свойство объектов Person, в то время как другие могут иметь свойства givenName & familyName. С JSON-LD вы можете сопоставить оба объекта с общим именем. Вы могли бы рассмотреть возможность взглянуть на эту ссылку:
Есть определенные преимущества интеграции HATEOAS в ваш код API в дополнение к использованию Swagger.
Swagger добавляет форму вашим API, делая их хорошо выглядящими и презентабельными, чтобы клиентский код мог быть написан легко, в то же время он также делает документацию гораздо менее скучной задачей, интегрируя ее с кодом. Излишне говорить, что это также экономит дополнительное время, необходимое для документирования, если это сделано после завершения кодирования. В этом смысле это немного революционно.
HATEOAS с другой стороны делает ваши API-интерфейсы самообнаруженными, включив Level 3 RMM. Это упрощает навигацию по одному API другому. Идея состоит в том, чтобы иметь базовый URL-адрес, который может использовать клиент, и остальные API-интерфейсы REST обнаруживаются на этом базовом URL-адресе.
Теперь вопрос в том, почему есть оба? Ну, это просто добавляет больше измерений к вашим Restful API и дает клиентам больше возможностей для очень мало усилий по кодированию. Кто бы этого не хотел?
Рассмотрим глядя в Hydra:
Hydra является словарь для JSON-LD, который позволяет вставлять элементы управления гипермедиа в ваших данных. Кроме того, вы можете предоставить конечную точку документации API, которая аналогична роли определения Swagger. Что мне нравится в Hydra, так это то, что элементы управления гипермедией выпекаются в ответах, а не живут вне группы в каком-то определенном сервисе. JSON-LD и Schema.org определенно заслуживают внимания, учитывая, как Google и Microsoft поддерживают их в своих продуктах.
Hydra по-прежнему относительно нова, поэтому доступная оснастка не такая сильная, как для Swagger.
Как разработчик, я лично просто посмотрю и попробую интерфейс Swagger, и я думаю, что большинство других разработчиков сделают то же самое. Являются ли другие варианты HATEOAS более полезными для чтения вашей машины API? Кроме того, HATEOAS обычно делает JSON более сложным для приложений, потому что у вас есть дополнительный шум (это решение, которое вы отвечаете только с HATEOS, если кто-то запрашивает его по типу MIME?). –
Как я уже сказал, HATEOS сделает ваш API Level 3 совместимым. Это эффективно означает, что ответы будут включать в себя _self, _next и _previous ссылки. Это упрощает навигацию для пользовательского интерфейса клиента. Я согласен с тем, что он имеет тенденцию становиться болтливым, но тогда для вас, как разработчика, количество ссылок для включения. – Sampada