The servant-docs package

[Tags:bsd3, library, program, test]

Library for generating API docs from a servant API definition.

Runnable example here.

CHANGELOG


[Skip to Readme]

Properties

Versions 0.2, 0.2.1, 0.3, 0.3.1, 0.4.0, 0.4.1, 0.4.2, 0.4.3, 0.4.3.1, 0.4.4, 0.4.4.2, 0.4.4.3, 0.4.4.4, 0.4.4.5, 0.4.4.6, 0.4.4.7, 0.5, 0.6, 0.6.1, 0.7, 0.7.1, 0.8, 0.8.1, 0.9, 0.9.0.1, 0.9.1, 0.9.1.1, 0.10, 0.10.0.1, 0.11 (info)
Change log CHANGELOG.md
Dependencies aeson, aeson-pretty, base (>=4.7 && <5), base-compat (>=0.9.1 && <0.10), bytestring, case-insensitive, control-monad-omega (==0.3.*), hashable, http-media (>=0.6), http-types (>=0.7), lens, semigroups (>=0.16.2.2 && <0.19), servant (==0.11.*), servant-docs, string-conversions, text, unordered-containers [details]
License BSD3
Copyright 2014-2016 Zalora South East Asia Pte Ltd, Servant Contributors
Author Servant Contributors
Maintainer haskell-servant-maintainers@googlegroups.com
Category Servant Web
Home page http://haskell-servant.readthedocs.org/
Bug tracker http://github.com/haskell-servant/servant/issues
Source repository head: git clone http://github.com/haskell-servant/servant.git
Uploaded Mon Jul 24 07:53:32 UTC 2017 by phadej
Distributions LTSHaskell:0.10.0.1, NixOS:0.11, Stackage:0.11, Tumbleweed:0.9.1.1
Downloads 3816 total (149 in the last 30 days)
Votes
1 []
Status Docs available [build log]
Last success reported on 2017-07-24 [all 1 reports]
Hackage Matrix CI

Modules

[Index]

Downloads

Maintainer's Corner

For package maintainers and hackage trustees

Readme for servant-docs

Readme for servant-docs-0.11

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