在 Servant 中生成端点描述

Question

Servant provides a way 根据 API 定义生成文档。但是，我看不到（非正式地）记录每个端点的功能的方法。对于上面link中使用的示例，生成的文档包含：

## 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 不支持这一点。但是，我想知道如何使用目前可用的方法解决这个问题。

Answer 1

相信在servant-docs(here)的Servant.Docs模块中可以找到你想要的东西。

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

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 函数的例子。

在 Servant 中生成端点描述

Generating end-point descriptions in Servant

haskell

servant