@@ -211,6 +211,46 @@ docsBS = encodeUtf8
211211
212212`docsWithIntros` just takes an additional parameter, a list of `DocIntro`s that must be displayed before any endpoint docs.
213213
214+More customisation can be done with the `markdownWith` function, which allows customising some of the parameters used when generating Markdown. The most obvious of these is how to handle when a request or response body has multiple content types. For example, if we make a slight change to the `/marketing` endpoint of our API so that the request body can also be encoded as a form:
215+
216+``` haskell
217+type ExampleAPI2 = "position" :> Capture "x" Int :> Capture "y" Int :> Get '[JSON] Position
218+ :<|> "hello" :> QueryParam "name" String :> Get '[JSON] HelloMessage
219+ :<|> "marketing" :> ReqBody '[JSON, FormUrlEncoded] ClientInfo :> Post '[JSON] Email
220+
221+exampleAPI2 :: Proxy ExampleAPI2
222+exampleAPI2 = Proxy
223+
224+api2Docs :: API
225+api2Docs = docs exampleAPI2
226+```
227+
228+The relevant output of `markdown api2Docs` is now:
229+
230+```````` text
231+#### Request:
232+
233+- Supported content types are:
234+
235+ - `application/json;charset=utf-8`
236+ - `application/json`
237+ - `application/x-www-form-urlencoded`
238+
239+- Example (`application/json;charset=utf-8`, `application/json`):
240+
241+ ```javascript
242+{"clientAge":26,"clientEmail":"alp@foo.com","clientName":"Alp","clientInterestedIn":["haskell","mathematics"]}
243+ ```
244+
245+- Example (`application/x-www-form-urlencoded`):
246+
247+ ```
248+clientAge=26&clientEmail=alp%40foo.com&clientName=Alp&clientInterestedIn=haskell&clientInterestedIn=mathematics
249+ ```
250+````````
251+
252+If, however, you don't want the extra example encoding shown, then you can use `markdownWith (defRenderingOptions & requestExamples .~ FirstContentType)` to get behaviour identical to `markdown apiDocs`.
253+
214254We can now serve the API *and* the API docs with a simple server.
215255
216256``` haskell