在僕人中生成端點描述

僕人provides a way從API定義中生成文檔。但是，我認爲沒有辦法（非正式）記錄每個端點的功能。對於上面的鏈接使用的示例中，生成的文檔包含：在僕人中生成端點描述

## Welcome 

This is our super webservice's API. 

Enjoy! 

## GET /hello 

#### GET Parameters: 

- name 
    - **Values**: *Alp, John Doe, ...* 
    - **Description**: Name of the person to say hello to. 


#### Response:

在上面的例子中，我懷念的是記錄了GET /hello終點呢，這是，我想有什麼辦法一種通過對每個端點的非正式描述來擴充API文檔的方法。

## Welcome 

This is our super webservice's API. 

Enjoy! 

## GET /hello 

Send a hello message to the given user. /<-- My description.../ 

#### GET Parameters: 

- name 
    - **Values**: *Alp, John Doe, ...* 
    - **Description**: Name of the person to say hello to. 


#### Response:

我的猜測是，這將需要標記不同的端點，以唯一標識它們，據我所知，僕人不支持。但是，我想知道如何用現在可用的解決方案來解決這個問題。

來源

2017-04-17 Damian Nadales

我簡要地看了一下這個文檔機制。對我來說沒有任何實際的投資是有用的，所以我只需託管一個靜態頁面，手工製作並手動保持API的最新狀態。在我的情況下，API幾乎不會改變（可能在一年內改變1次）。 –

我相信你在找什麼可以在模塊servant-docs（here）。

如果使用docsWith功能，你可以提供一個ExtraInfo對象爲您所記錄的API：

docsWith :: HasDocs api => DocOptions -> [DocIntro] -> ExtraInfo api -> Proxy api -> API

我相信docsWith的要點是允許你提供額外的端點文檔，你在問。 ExtraInfo有一個Monoid實例，所以看起來你可以爲你的api中的每個端點建立單獨的ExtraInfo對象，然後mappend將它們放在一起，並將其傳遞給docsWith。

要構建ExtraInfo，使用extraInfo功能：

extraInfo :: (IsIn endpoint api, HasLink endpoint, HasDocs endpoint) => Proxy endpoint -> Action -> ExtraInfo api

的文檔（與上文）有一個將如何去使用extraInfo功能的例子。

來源

2017-04-18 00:17:11 liminalisht

感謝您的提示，我可以添加自定義的「筆記」。它與我想要的不同之處在於添加一個註釋添加了一個新的部分，但它總比沒有好。現在我要試着在生成的Swagger文檔上做這個工作，但那是另一回事。 –

在僕人中生成端點描述

回答

相關問題