Eu tenho um serviço REST que quero documentar para minha equipe de desenvolvimento de clientes.

Então eu adicionei algunsLinks deSpring-Hateoas à minha API de recursos e conectado a elaswagger-springmvc @Api... anotações para documentar tudo e fazer uma boa referência de API para que minha equipe Angular possa entender meu serviço REST.

O problema é queswagger é incapaz de descobrir quais links são possíveis e me fornece uma grande variedade deLinks sem dizer seus possíveis valores.

Aqui está um exemplo (simples). O 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)
} 

E eu fico de fato no HAL:

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

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

Eu tentei estenderLink eResourceSupport ter anotado a versão deles, mas isso me levou a lugar nenhum.

Existe uma maneira / ferramenta que eu poderia usar para gerar um bom documento da API informando que umself relação é obter o conteúdo e umadelete relação é excluir a coleção?

Gostei do swagger por sua boa interface do usuário, mas não me importo de mudar minha ferramenta de documentação, se for de ajuda ter o documentorealmente completo.

Eu poderia eventualmente pensar em mudar o Spring-hateoas para outro gerador de link, mas não tenho certeza se existe uma ferramenta melhor disponível no momento.