History

Ivan Lazar Miljenovic 4f8df0ebe2 Make sure code blocks are indented in markdown documentation This relies on the behaviour of pandoc, and as such may not apply to other Markdown renderers. Before this change, you would have something like: > - Example: `application/json` > > ```javascript > "HELLO, HASKELLER" > ``` When converting this to HTML, PDF, etc. the code block is _not_ contained within the bullet point. With this change, the generated markdown looks like: > - Example: `application/json` > > ```javascript > "HELLO, HASKELLER" > ``` With pandoc at least, this effectively indents the entire code block to be under the bullet point, which is the intended effect. Note that the code itself is _not_ indented (which might break other Markdown renderers) as to do so would require splitting on newlines, which may have unintended consequences when dealing with generated values (may contain `\r\n`, etc.).		2017-10-05 16:29:43 +11:00
..
example	Replace all occurances of () with NoContent	2016-07-10 16:58:59 +02:00
include	less OverlappingInstances noise	2016-01-04 13:09:11 -05:00
src/Servant	Make sure code blocks are indented in markdown documentation	2017-10-05 16:29:43 +11:00
test	Fix tests for different GHC versions	2017-06-19 18:58:25 +03:00
.ghci	servant-docs: add .ghci	2016-01-18 12:28:29 +01:00
CHANGELOG.md	List content type with response examples	2017-09-22 14:12:13 +10:00
docs.sh	prepare merge	2015-04-20 11:19:48 +02:00
LICENSE	Change copyright to servant contributors	2016-01-20 16:58:29 +01:00
README.md	Import correct Servant module in README	2017-04-07 10:33:22 +10:00
servant-docs.cabal	Fix cabal category	2017-07-25 10:46:57 +03:00
Setup.hs	stylish haskell changes	2015-08-18 00:07:12 +02:00
tinc.yaml	Use tinc on travis	2015-11-05 09:32:13 +08:00

README.md

servant-docs

Generate API docs for your servant webservice. Feel free to also take a look at servant-pandoc which uses this package to target a broad range of output formats using the excellent pandoc.

Example

See here for the output of the following program.

{-# LANGUAGE DataKinds #-}
{-# LANGUAGE PolyKinds #-}
{-# LANGUAGE TypeFamilies #-}
{-# LANGUAGE DeriveGeneric #-}
{-# LANGUAGE TypeOperators #-}
{-# LANGUAGE FlexibleInstances #-}
{-# LANGUAGE OverloadedStrings #-}

import Data.Proxy
import Data.Text
import Servant.Docs

-- our type for a Greeting message
data Greet = Greet { _msg :: Text }
  deriving (Generic, Show)

-- we get our JSON serialization for free. This will be used by the default
-- 'MimeRender' instance for 'JSON'.
instance FromJSON Greet
instance ToJSON Greet

-- We can also implement 'MimeRender' explicitly for additional formats.
instance MimeRender PlainText Greet where
    mimeRender Proxy (Greet s) = "<h1>" <> cs s <> "</h1>"

-- we provide a sample value for the 'Greet' type
instance ToSample Greet where
  toSample = Just g

    where g = Greet "Hello, haskeller!"

instance ToParam (QueryParam "capital" Bool) where
  toParam _ =
    DocQueryParam "capital"
                  ["true", "false"]
                  "Get the greeting message in uppercase (true) or not (false). Default is false."

instance ToCapture (Capture "name" Text) where
  toCapture _ = DocCapture "name" "name of the person to greet"

instance ToCapture (Capture "greetid" Text) where
  toCapture _ = DocCapture "greetid" "identifier of the greet msg to remove"

-- API specification
type TestApi =
       "hello" :> Capture "name" Text :> QueryParam "capital" Bool :> Get '[JSON,PlainText] Greet
  :<|> "greet" :> RQBody '[JSON] Greet :> Post '[JSON] Greet
  :<|> "delete" :> Capture "greetid" Text :> Delete '[] ()

testApi :: Proxy TestApi
testApi = Proxy

-- Generate the Documentation's ADT
greetDocs :: API
greetDocs = docs testApi

main :: IO ()
main = putStrLn $ markdown greetDocs