Ich habe einen REST-Service, den ich für mein Kundenentwicklungsteam dokumentieren möchte.

Also habe ich welche hinzugefügtLinks vonSpring-Hateoas zu meiner Ressourcen-API und steckte in sieswagger-springmvc @Api... Anmerkungen, um alles zu dokumentieren und eine gute API-Referenz für mein Angular-Team zu erstellen, damit es meinen REST-Service verstehen kann.

Das Problem ist, dassswagger kann nicht erkennen, welche Links möglich sind, und gibt mir einfach eine große Auswahl anLinks ohne ihre möglichen Werte zu sagen.

Hier ist ein (einfaches) Beispiel. Swagger erkennt:

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

Und ich bekomme in der Tat in HAL:

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

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

Ich habe versucht zu verlängernLink undResourceSupport Version von ihnen kommentiert zu haben, aber dies führte mich nirgendwo hin.

Gibt es eine Möglichkeit / ein Tool, mit dem ich ein gutes API-Dokument erstellen kann, das besagt, dass aself Beziehung ist es, den Inhalt zu bekommen, und adelete beziehung ist die sammlung zu löschen?

Ich mochte Swagger wegen seiner guten Benutzeroberfläche, aber es macht mir nichts aus, mein Dokumentationswerkzeug zu ändern, wenn es dazu beiträgt, das Dokument zu habenJa wirklich Komplett.

Ich könnte irgendwann daran denken, spring-hateoas für einen anderen Link-Generator zu ändern, aber ich bin mir nicht sicher, ob es momentan ein besseres Tool gibt.