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 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 (info)
Change log CHANGELOG.md
Dependencies aeson (>=1.2.3.0 && <1.5), aeson-pretty (>=0.8.5 && <0.9), base (>=4.7 && <4.12), base-compat (>=0.9.3 && <0.11), bytestring (>=0.10.4.0 && <0.11), case-insensitive (>=1.2.0.10 && <1.3), control-monad-omega (>=0.3.1 && <0.4), hashable (>=1.2.6.1 && <1.3), http-media (>=0.7.0 && <0.8), http-types (==0.12.*), lens (>=4.15.4 && <4.18), semigroups (>=0.18.3 && <0.19), servant (>=0.13 && <0.15), servant-docs, string-conversions (>=0.4.0.1 && <0.5), text (>=1.2.3.0 && <1.3), unordered-containers (>=0.2.8.0 && <0.3) [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
Revised Revision 5 made by phadej at Thu Jul 5 15:58:15 UTC 2018
Category Servant, Web
Home page http://haskell-servant.readthedocs.org/
Bug tracker http://github.com/haskell-servant/servant/issues
Source repo head: git clone http://github.com/haskell-servant/servant.git
Uploaded by phadej at Fri Feb 9 13:21:03 UTC 2018
Distributions LTSHaskell:0.11.2, NixOS:0.11.2, Stackage:0.11.2
Executables greet-docs
Downloads 9764 total (97 in the last 30 days)
Rating 2.0 (votes: 1) [estimated by rule of succession]
Your Rating
  • λ
  • λ
  • λ
Status Docs available [build log]
Last success reported on 2018-02-09 [all 1 reports]
Hackage Matrix CI

Modules

[Index]

Downloads

Note: This package has metadata revisions in the cabal description newer than included in the tarball. To unpack the package including the revisions, use 'cabal get'.

Maintainer's Corner

For package maintainers and hackage trustees


Readme for servant-docs-0.11.2

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