servant-docs
generate API docs for your servant webservice
| Version on this page: | 0.11.9 |
| LTS Haskell 22.41: | 0.13.1 |
| Stackage Nightly 2024-11-12: | 0.13.1 |
| Latest on Hackage: | 0.13.1 |
Maintained by [email protected]
This version can be pinned in stack with:
servant-docs-0.11.9@sha256:e2b1e8a10ff615f0ac9dc2ff967cae8a4ec0b7704fe32fbd419131576cdd23cd,3292Module documentation for 0.11.9
Depends on 16 packages(full list with versions):
Used by 4 packages in nightly-2022-01-19(full list with versions):
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 DeriveGeneric #-}
{-# LANGUAGE FlexibleInstances #-}
{-# LANGUAGE MultiParamTypeClasses #-}
{-# LANGUAGE OverloadedStrings #-}
{-# LANGUAGE PolyKinds #-}
{-# LANGUAGE TypeFamilies #-}
{-# LANGUAGE TypeOperators #-}
import Data.Aeson (FromJSON, ToJSON)
import Data.Proxy (Proxy (..))
import Data.String.Conversions (cs)
import Data.Text (Text)
import GHC.Generics (Generic)
import Servant.API
( (:<|>),
(:>),
Capture,
Delete,
Get,
JSON,
MimeRender,
PlainText,
Post,
QueryParam,
ReqBody,
mimeRender,
)
import Servant.Docs
( API,
DocCapture (..),
DocQueryParam (..),
ParamKind (..),
ToCapture,
ToParam,
ToSample,
docs,
markdown,
singleSample,
toCapture,
toParam,
toSamples,
)
-- 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
instance ToSample ()
-- 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
toSamples _ = singleSample 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."
Normal
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" :> ReqBody '[JSON] Greet :> Post '[JSON] Greet
:<|> "delete" :> Capture "greetid" Text :> Delete '[JSON] ()
testApi :: Proxy TestApi
testApi = Proxy
-- Generate the Documentation's ADT
greetDocs :: API
greetDocs = docs testApi
main :: IO ()
main = putStrLn $ markdown greetDocs