У меня есть служба REST, которую я хочу документировать для моей команды разработчиков.
Итак, я добавил некоторые Links из Spring-Hateoas в API ресурсов и подключил к ним аннотации swagger-springmvc @Api... для документирования всего и создания хорошей ссылки API для моей команды Angular, чтобы иметь возможность понять моя служба REST.
Проблема заключается в том, что swagger не может обнаружить, какие ссылки возможны, и просто дайте мне большой массив Links, не сказав своих возможных значений.
Вот пример (простой). Swagger обнаруживает:
Model Schema
CollectionListResource {
collections (array[CollectionResource]): All available collections,
links (array[Link]): Relations for next actions
}
CollectionResource {
collectionId (string): Collection Unique Id,
name (string): Human readable collection name,
links (array[Link]): Relations for next actions
}
Link {
rel (string, optional),
templated (boolean, optional),
href (string, optional)
}
И я получаю на самом деле в HAL:
{"collections":
[{"collectionId":"5370a206b399c65f05a7c59e",
"name":"default",
"_links":{ [
"self":{
"href":"http://localhost:9080/collections/5370a206b399c65f05a7c59e"
},
"delete":{
"href":"http://localhost:9080/collections/5370a206b399c65f05a7c59e"
}
]}
}, ...]}
Я попытался расширить Link и ResourceSupport, чтобы иметь аннотированную версию, но это привело меня в никуда.
Есть ли способ/инструмент, который я мог бы использовать для создания хорошего документа API, сообщающего, что отношение self заключается в том, чтобы получить контент, а отношение delete - удалить коллекцию?
Мне понравился swagger для его хорошего пользовательского интерфейса, но я не возражаю изменить инструмент документации, если его помощь в том, что документ действительно завершен.
В конечном итоге я мог бы подумать об изменении spring -hateoas для другого генератора ссылок, но я не уверен, что сейчас есть лучший инструмент.