No description
Find a file
2015-02-07 15:23:54 +11:00
example Add initial mockup of general extra info API 2015-02-07 15:23:54 +11:00
src/Servant Add initial mockup of general extra info API 2015-02-07 15:23:54 +11:00
.gitignore Initial support for matrix parameters. Not complete, not sure how to document them yet, since documentation is focused on endpoints, not individual path fragments. 2015-01-01 23:42:06 +01:00
.travis.yml travis: buidl with ghc 7.8 and clone servant from git before building 2014-12-02 17:49:25 +01:00
CHANGELOG.md add a changelog 2015-01-04 17:17:57 +01:00
docs.sh adapt to the servant/servant-server split 2014-12-10 16:43:43 +01:00
LICENSE add LICENSE files to all projects 2014-12-01 16:38:43 +01:00
README.md mention servant-pandoc in the readme 2015-01-04 17:18:12 +01:00
servant-docs.cabal bump version 2015-01-04 17:18:40 +01:00
Setup.hs adapt to the servant/servant-server split 2014-12-10 16:43:43 +01:00

servant-docs

Build Status

servant

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

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

-- we get our JSON serialization for free
instance FromJSON Greet
instance ToJSON Greet

-- 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 Greet
  :<|> "greet" :> RQBody Greet :> Post 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