0

Servant提供了一种从 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:

我的猜测是，这将需要标记不同的端点以唯一地识别它们，据我所知，Servant 不支持。但是，我想知道如何用目前可用的东西来解决这个问题。

4

1 回答 1

3

我相信你要找的东西可以在（这里）的Servant.Docs模块中找到。servant-docs

如果您使用该docsWith函数，您可以ExtraInfo为您正在记录的 api 提供一个对象：

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

我相信重点docsWith是允许您按照您的要求提供额外的端点文档。有一个Monoid实例ExtraInfo，因此看起来您可以ExtraInfo为 api 中的每个端点构建单独的对象，然后将mappend它们组合在一起，并将其传递给docsWith.

要构建ExtraInfo，请使用以下extraInfo功能：

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

文档（链接到上面）有一个如何使用该extraInfo功能的示例。

于 2017-04-18T00:17:11.370 回答