У меня есть служба 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 для другого генератора ссылок, но я не уверен, что сейчас есть лучший инструмент.