來自Spring Hateoas的文檔HAL「_links」（與swagger）？

我想爲我的客戶開發團隊記錄一份REST服務。來自Spring Hateoas的文檔HAL「_links」（與swagger）？

所以我添加從Spring-Hateoas一些Links到我的資源API，並插入到它swagger-springmvc@Api...註解記錄的一切，使一個很好的API參考我的角團隊能夠理解我的REST服務。

問題是，swagger無法發現哪些鏈接是可能的，只是給我一大堆Links沒有說明它們的可能值。

這是一個（簡單）示例。揚鞭檢測：

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已經annoted他們的版本，但這個使我無處。

有沒有一種方法/工具可以用來生成一個好的API文檔，告訴self關係是獲取內容，而delete關係是刪除集合？

我很喜歡Swagger的良好用戶界面，但我不介意更改我的文檔工具，如果它的幫助文檔真的完成。

我最終可能會想到爲另一個鏈接生成器更改spring-hateoas，但我不確定現在是否有更好的工具可用。

來源

2014-06-24 JR Utily

Swagger-UI本身不是hypermedia aware;或至少它的限制，因爲它只能從頂級apis導航到api列表。這在規範2.0版本中並沒有太大的改變，其中值得注意的是增加了將外部文檔鏈接到帶外文檔。

您需要的是HAL browser和swagger-ui的混合。正如您正確地指出的那樣，「刪除」一詞與它在收集資源上下文中的含義之間存在語義鴻溝。 HAL使用curies和可選配置文件ALPS的組合來填補這一空白。 Curies只不過是命名空間的鏈接關係版本，所以它們不會與其他域相沖突。 Restful Web APIs是瞭解更多關於這些想法以及如何設計媒體類型的好資源。 spring data rest project也有一個很好的例子來說明如何實現這一點。

其中之一，我想辦法將工作是調整swagger specification支持面向視圖，而不是API上市定向視圖，而不是真的有可能在，你可能與工作時間內的操作。
使用現有的RFC（如rfc5023）對「編輯」資源意味着什麼有共同的理解。
最後，如果沒有任何標準鏈接關係表達動作的意圖，請定義您自己的應用程序特定語義，以提供這些應用程序特定鏈接關係的文檔。這樣，您的服務的客戶將在您的應用環境中對這些關係有共同的理解。

下面是一個演示和組合這些方法的示例。

{"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" 
     } 
    ]} 
    }, ...]}

因此，從最普通的到最具體的解決方案（按順序）是

IANA的限定鏈接有特定的含義，在這種情況下，「編輯」有一個非常特殊的意義每個安靜的客戶都可以實施。這是一個通用鏈接類型。
sw限定的鏈接關係也有特殊的含義，它意味着href深入鏈接到swagger api文檔中的操作。
col限定鏈接是應用程序特定的鏈接，只有您的應用程序知道。

我知道這並不能準確回答你的問題，而且這個空間中的工具還在不斷髮展。希望這可以幫助。

免責聲明：我是的core maintainers之一，它是一個彈簧集成解決方案，可以輕鬆提供大量的服務描述。所以任何關於如何解決這個問題的反饋都非常歡迎！

來源

2014-11-17 04:22:27

感謝您的所有參考;我已經知道一些，但發現了其他人。你提出的新HAL確實比我現在的更完整，但我仍然沒有看到一種方式來大舉發現_links數組的內容。實際上，現在我對HAL Spring爲我產生的感覺非常滿意。我不知道該解決方案是不是將通用_links數組轉換爲包含預定義可選鏈接字段的結構。從語法上講，實際上，刪除[]是「公正的」，但在實現方面，它肯定要複雜得多;） –

來自Spring Hateoas的文檔HAL「_links」（與swagger）？

回答

相關問題