在仆人中生成端点描述

仆人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文档上做这个工作，但那是另一回事。 –

在仆人中生成端点描述

回答

相关问题