Я использую Swagger для моего API-интерфейса ASP.NET с помощью Swashbuckle, который описывает мой API в отдельном документе и предоставляет хороший пользовательский интерфейс для всей этой информации.
Существуют ли какие-либо преимущества использования чего-то вроде HATEOAS, HAL или JSON-LD, которые изменяют сам документ в сочетании с Swagger?
Вот пример того, кто использует Swagger с HAL.
Как сказал сампада, оба - чванство и HATEOAS - добавляют большую ценность для разных измерений вашего api.
Swagger добавит ценность жизненному циклу разработки, делая ваш api более понятным и доступным для просмотра во время разработки.
HATEOAS добавит ценность вашему api при использовании клиентами. Ссылки, предоставляемые HATEOAS, дают вам возможность связывать разные части (то есть ресурсы) вашего api, не требуя жесткого кодирования этих ссылок в коде клиента вашего приложения.
Предполагая, что у вас есть контракт с несколькими документами, связанными с ним. Одним из наиболее распространенных способов моделирования этого было бы использование двух ресурсов:
Чтобы связать эти два вместе, вы можете добавлять поля в обе модели ресурсов, содержащие массивы соответствующего ресурса. Кроме того, вы должны реализовать эти неявные знания в своем клиентском приложении. Таким образом, вы будете добавлять беспорядок в свои представления ресурсов с течением времени, загрязняя его информацией об отношениях с другими объектами.
Именно здесь вступает в игру HATEOAS, как перемещая эту информацию об операциях из ваших бизнес-объектов, так и предоставляя единый способ справиться с этими отношениями. Оба бизнес-объекта ресурсов теперь будут включать один стандартизованный заголовок или значение-поле, содержащее информацию обо всех отношениях текущего ресурса. Например, у одного ресурса контракта теперь будет 3 ссылки с rel-attribute "document", связывающие с соответствующими ресурсами документа и 1 ссылку с rel-attribute "order", связывающую с порядком, в результате которого был заключен этот контракт.
Насколько я знаю, JSON-LD используется для нормализации словаря различных API, что упрощает их использование бок о бок. Некоторые могут использовать firstName & lastName как свойство объектов Person, в то время как другие будут иметь имя properties givenName & familyName. С JSON-LD вы можете сопоставить оба объекта с общим именем. Вы можете рассмотреть возможность взглянуть на эту ссылку: DZone - Json-LD
Существуют определенные преимущества интеграции HATEOAS в ваш код API в дополнение к использованию Swagger.
Swagger добавляет форму вашим API, делая их хорошо выглядящими и презентабельными, чтобы клиентский код мог быть легко написан, в то же время он также делает документацию гораздо менее скучной задачей, интегрируя ее с кодом. Излишне говорить, что это также экономит дополнительное время, необходимое для документирования, если это сделано после завершения кодирования. В этом смысле это немного революционно.
HATEOAS другой стороны, HATEOAS делает ваш API HATEOAS для себя, позволяя 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.