Documento HAL "_links" da Spring hateoas (con spavalderia)?

Question

Ho un servizio REST voglio documentare per il mio cliente lo sviluppo di squadra.

così ho aggiunto un po 'di Links da Spring-Hateoas al mio API risorse, e collegato a esso swagger-springmvc@Api... annotazioni di documentare tutto e fare un buon riferimento API per la mia squadra angolare per essere in grado di capire il mio servizio REST.

Il problema è che swagger non è in grado di scoprire quali collegamenti sono possibili, e semplicemente darmi una grande serie di Links senza dire i loro possibili valori.

Ecco una (semplice) esempio. Swagger rileva:

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 ottengo infatti nel HAL:

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

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

Ho cercato di estendere Link e ResourceSupport per aver annotata versione di loro, ma questo mi porterà da nessuna parte.

C'è un modo/uno strumento che potrei usare per generare un buon documento API che dice che una relazione self è quella di ottenere il contenuto e una relazione delete è quella di eliminare la raccolta?

Mi piaceva lo swagger per la sua buona interfaccia utente, ma non mi importa cambiare il mio strumento di documentazione se il suo aiuto con il documento è davvero completo.

potevo finalmente pensare di cambiare a molla hateoas per un altro generatore di collegamento, ma non sono sicuro che ci sia uno strumento migliore disponibile al momento.

Answer 1

Swagger-UI come tale non è hypermedia aware; o almeno il suo limite in quanto può navigare SOLO dalle apis di livello superiore alle schede API. Che non è cambiato molto nel v2.0 delle specifiche sia, con la notevole aggiunta di link a documenti esterni per di documentazione band.

Quello che ti serve è un ibrido di HAL browser e swagger-ui. Come hai giustamente sottolineato, c'è un divario semantico tra la parola "cancella" e ciò che significa nel contesto di una risorsa di raccolta. HAL usa una combinazione di curies e opzionalmente un documento di profilo ALPS per colmare questa lacuna. I curie non sono altro che versioni con nomi di relazioni legate in modo che non entrino in collisione con altri domini. Restful Web APIs è una grande risorsa per saperne di più su queste idee e su come progettare i tipi di media. Lo spring data rest project ha anche un ottimo esempio di come ottenerlo.

• Uno dei modi che penso sarebbe lavoro è quello di regolare swagger specification a sostegno di una vista operazioni piuttosto che API orientate messa in vendita di vista orientato, non è davvero possibile nel lasso di tempo che la si sta forse lavorando con.
• Utilizzare gli RFC esistenti come rfc5023 per avere una comprensione condivisa di cosa significhi "modificare" una risorsa.
• Infine, se nessuna delle relazioni di collegamento standard esprime l'intento dell'azione, definire la propria semantica specifica dell'applicazione che fornisce la documentazione per queste relazioni di collegamento specifiche dell'applicazione. In questo modo i clienti del tuo servizio avranno una comprensione condivisa di queste relazioni nel contesto della tua applicazione.

Di seguito è un esempio che dimostra e combina questi approcci.

{"collections": 
[{"collectionId":"5370a206b399c65f05a7c59e", 
    "name":"default", 
    "curies": [ 
     { 
      "name": "sw", 
      "href": "http://swagger.io/rels/{rel}", 
      "templated": true 
     }, 
     { 
      "name": "iana", 
      "href": "http://tools.ietf.org/html/rfc5023", 
      "templated": false 
     }, 
     { 
      "name": "col", 
      "href": "http://localhost:9080/collections/{rel}", 
      "templated": false 
     } 
    ], 
    "_links":{ [ 
     "self":{ 
      "href":"http://localhost:9080/collections/5370a206b399c65f05a7c59e" 
     }, 
     "sw:operation":{ 
      "href":"http://localhost:9080/api-docs/collections#delete" 
     }, 
     "sw:operation":{ 
      "href":"http://localhost:9080/api-docs/collections#search" 
     }, 
     "sw:operation":{ 
      "href":"http://localhost:9080/api-docs/collections#update" 
     }, 
     "iana:edit":{ 
      "href":"http://localhost:9080/collections/5370a206b399c65f05a7c59e" 
     }, 
     "col:delete": { 
      "href":"http://localhost:9080/collections/5370a206b399c65f05a7c59e" 
     } 
    ]} 
    }, ...]} 

Così da più generico per più specifica, la soluzione (in questo ordine) è

• IANA collegamenti qualificati hanno un significato specifico, in questo caso la "modifica" ha un significato molto specifico che ogni cliente riposante può implementare. Questo è un tipo di collegamento generializzato.
• Anche le relazioni di collegamento qualificate sw hanno un significato speciale, implicano i collegamenti profondi con href alle operazioni nella documentazione di swagger api.
• I collegamenti qualificati sono collegamenti specifici dell'applicazione di cui solo la vostra applicazione è a conoscenza.

So che questo non risponde alla tua domanda con precisione, e gli strumenti in questo spazio sono ancora in evoluzione. Spero che questo ti aiuti.

NOTA BENE: Sono uno dei core maintainers di springfox che è una soluzione di integrazione di primavera che rende facile fornire descrizioni di servizio swagger. Quindi qualsiasi feedback su come ti piacerebbe risolvere questo problema è molto gradito!