eeva/servant
1
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

tutorial: read through Docs.lhs

Browse source
This commit is contained in:
Sönke Hahn 2016-02-28 22:32:53 +01:00
parent 624e220450
commit 338656b2ce
1 changed files with 60 additions and 60 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

78
doc/tutorial/Docs.lhs
View file

@ -26,7 +26,7 @@ import Servant.Server
``` ```
And we'll import some things from one of our earlier modules And we'll import some things from one of our earlier modules
([Serving an API](/tutorial/server.html)): ([Serving an API](Server.html)):
``` haskell ``` haskell
import Server (Email(..), ClientInfo(..), Position(..), HelloMessage(..), import Server (Email(..), ClientInfo(..), Position(..), HelloMessage(..),
@ -35,7 +35,7 @@ import Server (Email(..), ClientInfo(..), Position(..), HelloMessage(..),
Like client function generation, documentation generation amounts to inspecting the API type and extracting all the data we need to then present it in some format to users of your API. Like client function generation, documentation generation amounts to inspecting the API type and extracting all the data we need to then present it in some format to users of your API.
This time however, we have to assist *servant*. While it is able to deduce a lot of things about our API, it can't magically come up with descriptions of the various pieces of our APIs that are human-friendly and explain what's going on "at the business-logic level". A good example to study for documentation generation is our webservice with the `/position`, `/hello` and `/marketing` endpoints from earlier: This time however, we have to assist **servant**. While it is able to deduce a lot of things about our API, it can't magically come up with descriptions of the various pieces of our APIs that are human-friendly and explain what's going on "at the business-logic level". A good example to study for documentation generation is our webservice with the `/position`, `/hello` and `/marketing` endpoints from earlier:
``` haskell ``` haskell
type ExampleAPI = "position" :> Capture "x" Int :> Capture "y" Int :> Get '[JSON] Position type ExampleAPI = "position" :> Capture "x" Int :> Capture "y" Int :> Get '[JSON] Position
@ -46,7 +46,7 @@ exampleAPI :: Proxy ExampleAPI
exampleAPI = Proxy exampleAPI = Proxy
``` ```
While *servant* can see e.g. that there are 3 endpoints and that the response bodies will be in JSON, it doesn't know what influence the captures, parameters, request bodies and other combinators have on the webservice. This is where some manual work is required. While **servant** can see e.g. that there are 3 endpoints and that the response bodies will be in JSON, it doesn't know what influence the captures, parameters, request bodies and other combinators have on the webservice. This is where some manual work is required.
For every capture, request body, response body, query param, we have to give some explanations about how it influences the response, what values are possible and the likes. Here's how it looks like for the parameters we have above. For every capture, request body, response body, query param, we have to give some explanations about how it influences the response, what values are possible and the likes. Here's how it looks like for the parameters we have above.
@ -97,9 +97,9 @@ apiDocs :: API
apiDocs = docs exampleAPI apiDocs = docs exampleAPI
``` ```
`API` is a type provided by *servant-docs* that stores all the information one needs about a web API in order to generate documentation in some format. Out of the box, *servant-docs* only provides a pretty documentation printer that outputs [Markdown](http://en.wikipedia.org/wiki/Markdown), but the [servant-pandoc](http://hackage.haskell.org/package/servant-pandoc) package can be used to target many useful formats. `API` is a type provided by **servant-docs** that stores all the information one needs about a web API in order to generate documentation in some format. Out of the box, **servant-docs** only provides a pretty documentation printer that outputs [Markdown](http://en.wikipedia.org/wiki/Markdown), but the [**servant-pandoc**](http://hackage.haskell.org/package/servant-pandoc) package can be used to target many useful formats.
*servant*'s markdown pretty printer is a function named `markdown`. **servant**'s markdown pretty printer is a function named `markdown`.
``` haskell ignore ``` haskell ignore
markdown :: API -> String markdown :: API -> String
@ -107,97 +107,97 @@ markdown :: API -> String
That lets us see what our API docs look down in markdown, by looking at `markdown apiDocs`. That lets us see what our API docs look down in markdown, by looking at `markdown apiDocs`.
``` text ````````` text
## Welcome ## Welcome
This is our super webservice's API. This is our super webservice's API.
Enjoy! Enjoy!
## GET /hello ## GET /hello
#### GET Parameters: #### GET Parameters:
- name - name
- **Values**: *Alp, John Doe, ...* - **Values**: *Alp, John Doe, ...*
- **Description**: Name of the person to say hello to. - **Description**: Name of the person to say hello to.
#### Response: #### Response:
- Status code 200 - Status code 200
- Headers: [] - Headers: []
- Supported content types are: - Supported content types are:
- `application/json` - `application/json`
- When a value is provided for 'name' - When a value is provided for 'name'
```javascript ```javascript
{"msg":"Hello, Alp"} {"msg":"Hello, Alp"}
``` ```
- When 'name' is not specified - When 'name' is not specified
```javascript ```javascript
{"msg":"Hello, anonymous coward"} {"msg":"Hello, anonymous coward"}
``` ```
## POST /marketing ## POST /marketing
#### Request: #### Request:
- Supported content types are: - Supported content types are:
- `application/json` - `application/json`
- Example: `application/json` - Example: `application/json`
```javascript ```javascript
{"email":"alp@foo.com","interested_in":["haskell","mathematics"],"age":26,"name":"Alp"} {"email":"alp@foo.com","interested_in":["haskell","mathematics"],"age":26,"name":"Alp"}
``` ```
#### Response: #### Response:
- Status code 201 - Status code 201
- Headers: [] - Headers: []
- Supported content types are: - Supported content types are:
- `application/json` - `application/json`
- Response body as below. - Response body as below.
```javascript ```javascript
{"subject":"Hey Alp, we miss you!","body":"Hi Alp,\n\nSince you've recently turned 26, have you checked out our latest haskell, mathematics products? Give us a visit!","to":"alp@foo.com","from":"great@company.com"} {"subject":"Hey Alp, we miss you!","body":"Hi Alp,\n\nSince you've recently turned 26, have you checked out our latest haskell, mathematics products? Give us a visit!","to":"alp@foo.com","from":"great@company.com"}
``` ```
## GET /position/:x/:y ## GET /position/:x/:y
#### Captures: #### Captures:
- *x*: (integer) position on the x axis - *x*: (integer) position on the x axis
- *y*: (integer) position on the y axis - *y*: (integer) position on the y axis
#### Response: #### Response:
- Status code 200 - Status code 200
- Headers: [] - Headers: []
- Supported content types are: - Supported content types are:
- `application/json` - `application/json`
- Response body as below. - Response body as below.
```javascript ```javascript
{"x":3,"y":14} {"x":3,"y":14}
``` ```
``` `````````
However, we can also add one or more introduction sections to the document. We just need to tweak the way we generate `apiDocs`. We will also convert the content to a lazy `ByteString` since this is what *wai* expects for `Raw` endpoints. However, we can also add one or more introduction sections to the document. We just need to tweak the way we generate `apiDocs`. We will also convert the content to a lazy `ByteString` since this is what **wai** expects for `Raw` endpoints.
``` haskell ``` haskell
docsBS :: ByteString docsBS :: ByteString
@ -231,4 +231,4 @@ app :: Application
app = serve api server app = serve api server
``` ```
And if you spin up this server with `dist/build/tutorial/tutorial 10` and go to anywhere else than `/position`, `/hello` and `/marketing`, you will see the API docs in markdown. This is because `serveDocs` is attempted if the 3 other endpoints don't match and systematically succeeds since its definition is to just return some fixed bytestring with the `text/plain` content type. And if you spin up this server and request anything else than `/position`, `/hello` and `/marketing`, you will see the API docs in markdown. This is because `serveDocs` is attempted if the 3 other endpoints don't match and systematically succeeds since its definition is to just return some fixed bytestring with the `text/plain` content type.