@@ -211,6 +211,46 @@ docsBS = encodeUtf8
212`docsWithIntros` just takes an additional parameter, a list of `DocIntro`s that must be displayed before any endpoint docs.
212`docsWithIntros` just takes an additional parameter, a list of `DocIntro`s that must be displayed before any endpoint docs.
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:
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
221+exampleAPI2 :: Proxy ExampleAPI2
225+api2Docs = docs exampleAPI2
228+The relevant output of `markdown api2Docs` is now:
233+- Supported content types are:
235+ - `application/json;charset=utf-8`
236+ - `application/json`
237+ - `application/x-www-form-urlencoded`
239+- Example (`application/json;charset=utf-8`, `application/json`):
242+{"clientAge":26,"clientEmail":"alp@foo.com","clientName":"Alp","clientInterestedIn":["haskell","mathematics"]}
245+- Example (`application/x-www-form-urlencoded`):
248+clientAge=26&clientEmail=alp%40foo.com&clientName=Alp&clientInterestedIn=haskell&clientInterestedIn=mathematics
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`.
214We can now serve the API *and* the API docs with a simple server.
254We can now serve the API *and* the API docs with a simple server.
216``` haskell
256``` haskell