Generating end-point descriptions in Servant

Question

Servant provides a way to generate documentation from the API definition. However, I see no way of (informally) documenting the functionality of each end-point. For the example used in the link above, the generated documentation contains:

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

In the example above, what I miss is a way of documenting what the GET /hello end-point does, this is, I would like to have a way to augmenting the API docs with an informal description of each end-point.

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

My guess is that this will require tagging the different end-points to identify them uniquely, something that as far as I know Servant does not support. However, I'm wondering how to solve this problem with what is available as of now.

I looked at that documentation mechanism briefly. It wasn't useful enough for me to justify any real time investment so I just host a static page, hand crafted and manually kept up-to-date with the API. In my case it helps that the API pretty much never changes (perhaps 1 change in over a year). — Thomas M. DuBuisson, Apr 17 '17 at 16:32

score 3 · Accepted Answer · answered Apr 18 '17 at 00:17

I believe what you are looking for can be found in the Servant.Docs module of servant-docs (here).

If you use the docsWith function, you can supply an ExtraInfo object for the api you are documenting:

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

I believe that the point of docsWith is to allow you to supply extra endpoint documentation, as you are asking. There is a Monoid instance for ExtraInfo, so it looks like you can build separate ExtraInfo objects for each endpoint in your api, then mappend them together, and pass this to docsWith.

To build ExtraInfo, use the extraInfo function:

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

The documentation (linked to above) has an example of how one would go about using the extraInfo function.

Thanks with your tips I was able to add custom `notes`. It differs from what I wanted in that adding a note adds a new section, but it is better than nothing. Now I'm gonna try to make this work on generated Swagger docs, but that's another story. — Damian Nadales, Apr 18 '17 at 16:14

Generating end-point descriptions in Servant

1 Answers1