servant-docs: generate API docs for your servant webservice

[ bsd3, library, program, servant, web ] [ Propose Tags ]

Library for generating API docs from a servant API definition.

Runnable example here.

CHANGELOG


[Skip to Readme]
Versions [faq] 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, 0.11.1, 0.11.2, 0.11.3, 0.11.4 (info)
Change log CHANGELOG.md
Dependencies aeson, aeson-pretty, base (>=4.7 && <5), bytestring, bytestring-conversion, case-insensitive, control-monad-omega (==0.3.*), hashable, http-media (>=0.6), http-types (>=0.7), lens, servant (==0.6.*), servant-docs, string-conversions, text, unordered-containers [details]
License BSD-3-Clause
Copyright 2014-2016 Zalora South East Asia Pte Ltd, Servant Contributors
Author Servant Contributors
Maintainer haskell-servant-maintainers@googlegroups.com
Category Web
Home page http://haskell-servant.github.io/
Bug tracker http://github.com/haskell-servant/servant/issues
Source repo head: git clone http://github.com/haskell-servant/servant.git
Uploaded by SoenkeHahn at Mon Apr 4 08:50:25 UTC 2016
Distributions LTSHaskell:0.11.3, NixOS:0.11.4, Stackage:0.11.3
Executables greet-docs
Downloads 15901 total (528 in the last 30 days)
Rating 2.0 (votes: 1) [estimated by rule of succession]
Your Rating
  • λ
  • λ
  • λ
Status Hackage Matrix CI
Docs available [build log]
Last success reported on 2016-05-17 [all 1 reports]

Modules

[Index]

Downloads

Maintainer's Corner

For package maintainers and hackage trustees


Readme for servant-docs-0.6

[back to package description]

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

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