Tengo un servicio REST que quiero documentar para mi equipo de desarrollo de clientes.

Entonces agregué algunosLinks deSpring-Hateoas a mi API de recursos y conectadoswagger-springmvc @Api... anotaciones para documentar todo y hacer una buena referencia de API para que mi equipo angular pueda comprender mi servicio REST.

El problema es eseswagger no puede descubrir qué enlaces son posibles, y solo dame una gran variedad deLinks sin decir sus posibles valores.

Aquí hay un ejemplo (simple). Swagger detecta:

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)
} 

Y de hecho me pongo en HAL:

 {"collections":
    [{"collectionId":"5370a206b399c65f05a7c59e",
      "name":"default",
       "_links":{ [
           "self":{
              "href":"http://localhost:9080/collections/5370a206b399c65f05a7c59e"
            },

           "delete":{
              "href":"http://localhost:9080/collections/5370a206b399c65f05a7c59e"
            }
        ]}
       }, ...]}   

He tratado de extenderLink yResourceSupport tener una versión anotada de ellos, pero esto no me lleva a ninguna parte.

¿Hay alguna forma / herramienta que pueda usar para generar un buen documento de API que indique que unself relación es obtener el contenido, y unadelete relación es eliminar la colección?

Me gustó Swagger por su buena interfaz de usuario, pero no me importa cambiar mi herramienta de documentación si es útil tener el documentoDe Verdad completar.

Eventualmente podría pensar en cambiar spring-hateoas por otro generador de enlaces, pero no estoy seguro de que haya una mejor herramienta disponible en este momento.