Skip to content

Files

Latest commit

d06a2dd · Nov 20, 2023

History

History
This branch is 2 commits ahead of, 267 commits behind haskell-servant/servant:master.

servant-docs

Folders and files

NameName
Last commit message
Last commit date

parent directory

..
Aug 19, 2021
Dec 29, 2022
Mar 9, 2023
Aug 19, 2021
Jan 18, 2016
Jun 23, 2023
Nov 13, 2018
Sep 3, 2020
Aug 17, 2015
Apr 20, 2015
Nov 20, 2023

servant-docs

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 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