@@ -26,7 +26,7 @@ import Servant.Server
2626```
2727
2828And we'll import some things from one of our earlier modules
29−([Serving an API](/tutorial/server.html)):
29+([Serving an API](Server.html)):
3030
3131``` haskell
3232import Server (Email(..), ClientInfo(..), Position(..), HelloMessage(..),
@@ -35,7 +35,7 @@ import Server (Email(..), ClientInfo(..), Position(..), HelloMessage(..),
3535
3636Like 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.
3737
38−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:
38+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:
3939
4040``` haskell
4141type ExampleAPI = "position" :> Capture "x" Int :> Capture "y" Int :> Get '[JSON] Position
@@ -46,7 +46,7 @@ exampleAPI :: Proxy ExampleAPI
4646exampleAPI = Proxy
4747```
4848
49−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.
49+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.
5050
5151For 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.
5252
@@ -97,9 +97,9 @@ apiDocs :: API
9797apiDocs = docs exampleAPI
9898```
9999
100−`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.
100+`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.
101101
102−*servant*'s markdown pretty printer is a function named `markdown`.
102+**servant**'s markdown pretty printer is a function named `markdown`.
103103
104104``` haskell ignore
105105markdown :: API -> String
@@ -107,97 +107,97 @@ markdown :: API -> String
107107
108108That lets us see what our API docs look down in markdown, by looking at `markdown apiDocs`.
109109
110−``` text
111− ## Welcome
110+````````` text
111+## Welcome
112112
113− This is our super webservice's API.
113+This is our super webservice's API.
114114
115− Enjoy!
115+Enjoy!
116116
117− ## GET /hello
117+## GET /hello
118118
119− #### GET Parameters:
119+#### GET Parameters:
120120
121− - name
122− - **Values**: *Alp, John Doe, ...*
123− - **Description**: Name of the person to say hello to.
121+- name
122+ - **Values**: *Alp, John Doe, ...*
123+ - **Description**: Name of the person to say hello to.
124124
125125
126− #### Response:
126+#### Response:
127127
128− - Status code 200
129− - Headers: []
128+- Status code 200
129+- Headers: []
130130
131− - Supported content types are:
131+- Supported content types are:
132132
133− - `application/json`
133+ - `application/json`
134134
135− - When a value is provided for 'name'
135+- When a value is provided for 'name'
136136
137− ```javascript
138− {"msg":"Hello, Alp"}
139− ```
137+ ```javascript
138+ {"msg":"Hello, Alp"}
139+ ```
140140
141− - When 'name' is not specified
141+- When 'name' is not specified
142142
143− ```javascript
144− {"msg":"Hello, anonymous coward"}
145− ```
143+ ```javascript
144+ {"msg":"Hello, anonymous coward"}
145+ ```
146146
147− ## POST /marketing
147+## POST /marketing
148148
149− #### Request:
149+#### Request:
150150
151− - Supported content types are:
151+- Supported content types are:
152152
153− - `application/json`
153+ - `application/json`
154154
155− - Example: `application/json`
155+- Example: `application/json`
156156
157− ```javascript
158− {"email":"alp@foo.com","interested_in":["haskell","mathematics"],"age":26,"name":"Alp"}
159− ```
157+ ```javascript
158+ {"email":"alp@foo.com","interested_in":["haskell","mathematics"],"age":26,"name":"Alp"}
159+ ```
160160
161− #### Response:
161+#### Response:
162162
163− - Status code 201
164− - Headers: []
163+- Status code 201
164+- Headers: []
165165
166− - Supported content types are:
166+- Supported content types are:
167167
168− - `application/json`
168+ - `application/json`
169169
170− - Response body as below.
170+- Response body as below.
171171
172− ```javascript
173− {"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"}
174− ```
172+ ```javascript
173+ {"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"}
174+ ```
175175
176− ## GET /position/:x/:y
176+## GET /position/:x/:y
177177
178− #### Captures:
178+#### Captures:
179179
180− - *x*: (integer) position on the x axis
181− - *y*: (integer) position on the y axis
180+- *x*: (integer) position on the x axis
181+- *y*: (integer) position on the y axis
182182
183− #### Response:
183+#### Response:
184184
185− - Status code 200
186− - Headers: []
185+- Status code 200
186+- Headers: []
187187
188− - Supported content types are:
188+- Supported content types are:
189189
190− - `application/json`
190+ - `application/json`
191191
192− - Response body as below.
192+- Response body as below.
193193
194− ```javascript
195− {"x":3,"y":14}
196− ```
194+ ```javascript
195+ {"x":3,"y":14}
196+ ```
197197
198−```
198+`````````
199199
200−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.
200+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.
201201
202202``` haskell
203203docsBS :: ByteString
@@ -231,4 +231,4 @@ app :: Application
231231app = serve api server
232232```
233233
234−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.
234+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.