Question

Servant 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:

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

Answer 1

我相信您所寻找的内容可以在Servant.Docs（here）的servant-docs模块中找到。

如果您使用docsWith功能，则可以为您正在记录的API提供ExtraInfo个对象：

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

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

要构建ExtraInfo，请使用extraInfo函数：

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

文档（链接到上面）有一个例子，说明如何使用extraInfo函数。

在Servant中生成端点描述

1 个答案: