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.


[Skip to Readme]

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

Versions [RSS] 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, 0.11.5, 0.11.6, 0.11.7, 0.11.8, 0.11.9, 0.12, 0.13 (info)
Change log CHANGELOG.md
Dependencies aeson, aeson-pretty (<0.8), base (>=4.7 && <5), bytestring, hashable, lens (<4.13), servant (>=0.2.1 && <0.4), servant-docs, string-conversions, system-filepath, text, unordered-containers [details]
License BSD-3-Clause
Copyright 2014-2015 Zalora South East Asia Pte Ltd
Author Alp Mestanogullari, Sönke Hahn, Julian K. Arni
Maintainer alpmestan@gmail.com
Revised Revision 1 made by phadej at 2017-12-10T22:40:08Z
Category Web
Home page http://haskell-servant.github.io/
Bug tracker http://github.com/haskell-servant/servant-docs/issues
Source repo head: git clone http://github.com/haskell-servant/servant-docs.git
Uploaded by jkarni at 2015-03-02T14:23:50Z
Distributions LTSHaskell:0.13, NixOS:0.13, Stackage:0.13
Reverse Dependencies 24 direct, 28 indirect [details]
Executables greet-docs
Downloads 35426 total (189 in the last 30 days)
Rating 2.0 (votes: 1) [estimated by Bayesian average]
Your Rating
  • λ
  • λ
  • λ
Status Docs available [build log]
Last success reported on 2015-03-02 [all 2 reports]

Readme for servant-docs-0.3.1

[back to package description]

servant-docs

Build Status

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
instance FromJSON Greet
instance ToJSON Greet

-- 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 Greet
  :<|> "greet" :> RQBody Greet :> Post 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