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:

私の推測では、これには異なるエンドポイントにタグを付けて一意に識別する必要があると思います。これは、私が知る限り、サーバントがサポートしていないものです。ただし、現在利用可能なものでこの問題を解決する方法を考えています。

4

1 に答える 1

3

あなたが探しているものは( hereServant.Docs ) のモジュールで見つかると思います。servant-docs

docsWithこの関数を使用すると、ExtraInfo文書化する API のオブジェクトを指定できます。

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

docsWithあなたが求めているように、追加のエンドポイント ドキュメントを提供できるようにすることがポイントだと思います。のMonoidインスタンスがあるため、API のエンドポイントごとにExtraInfo個別のオブジェクトを構築し、それらをまとめて、これを に渡すことができるようです。ExtraInfomappenddocsWith

をビルドするには、次の関数ExtraInfoを使用します。extraInfo

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

ドキュメント（上記にリンクされています）には、extraInfo関数の使用方法の例があります。

于 2017-04-18T00:17:11.370 に答える