servant/servant-docs/src/Servant/Docs.hs

58 lines
1.9 KiB
Haskell
Raw Normal View History

-------------------------------------------------------------------------------
2015-04-08 16:27:38 +02:00
-- | This module lets you get API docs for free. It lets you generate
-- an 'API' from the type that represents your API using 'docs':
--
-- @docs :: 'HasDocs' api => 'Proxy' api -> 'API'@
--
2015-04-08 16:27:38 +02:00
-- Alternatively, if you wish to add one or more introductions to your
-- documentation, use 'docsWithIntros':
--
2015-04-08 16:27:38 +02:00
-- @'docsWithIntros' :: 'HasDocs' api => [DocIntro] -> 'Proxy' api -> 'API'@
--
-- You can then call 'markdown' on the 'API' value:
--
2015-04-08 16:27:38 +02:00
-- @'markdown' :: 'API' -> String@
--
-- or define a custom pretty printer:
--
-- @yourPrettyDocs :: 'API' -> String -- or blaze-html's HTML, or ...@
--
-- The only thing you'll need to do will be to implement some classes
-- for your captures, get parameters and request or response bodies.
--
-- See example/greet.hs for an example.
module Servant.Docs
( -- * 'HasDocs' class and key functions
2015-12-10 03:04:47 +01:00
HasDocs(..), docs, pretty, markdown
-- * Generating docs with extra information
, docsWith, docsWithIntros, docsWithOptions
, ExtraInfo(..), extraInfo
, DocOptions(..) , defaultDocOptions, maxSamples
, -- * Classes you need to implement for your types
ToSample(..)
, toSample
, noSamples
, singleSample
, samples
, sampleByteString
, sampleByteStrings
, ToParam(..)
, ToCapture(..)
, -- * ADTs to represent an 'API'
Method(..)
, Endpoint, path, method, defEndpoint
, API, apiIntros, apiEndpoints, emptyAPI
, DocCapture(..), capSymbol, capDesc
, DocQueryParam(..), ParamKind(..), paramName, paramValues, paramDesc, paramKind
, DocNote(..), noteTitle, noteBody
, DocIntro(..), introTitle, introBody
2015-04-08 16:27:38 +02:00
, Response(..), respStatus, respTypes, respBody, defResponse
, Action, captures, headers, notes, params, rqtypes, rqbody, response, defAction
, single
) where
2015-12-10 21:27:15 +01:00
import Servant.Docs.Internal
import Servant.Docs.Internal.Pretty