-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/
-- | Generate endpoints overview for Servant API
--
-- This library uses Data.Typeable to generate documentation for
-- Servant API types. It relies on the typeRep of Servant's
-- combinators and other datatypes used in the API to generate the
-- documentation.
@package servant-docs-simple
@version 0.2.0.0
-- | Renders the intermediate structure into common documentation formats
--
-- Example scripts
--
-- Generating plaintext/JSON documentation from api types
--
-- Writing our own rendering format
--
-- Example of rendering the intermediate structure
--
-- Intermediate structure
--
--
-- ApiDocs ( fromList [( "/hello/world",
-- , Details (fromList ([ ( "RequestBody"
-- , Details (fromList ([ ( "Format"
-- , Detail "': * () ('[] *)"
-- )
-- , ( "ContentType"
-- , Detail "()"
-- )
-- ]))
-- )
-- , ( "RequestType"
-- , Detail "'POST"
-- )
-- , ( "Response"
-- , Details (fromList ([ ( "Format"
-- , Detail "': * () ('[] *)"
-- )
-- , ( "ContentType"
-- , Detail "()"
-- )
-- ]))
-- )
-- ]))
-- )])
--
--
-- JSON
--
--
-- {
-- "/hello/world": {
-- "Response": {
-- "Format": "': * () ('[] *)",
-- "ContentType": "()"
-- },
-- "RequestType": "'POST",
-- "RequestBody": {
-- "Format": "': * () ('[] *)",
-- "ContentType": "()"
-- }
-- }
-- }
--
--
-- Text
--
--
-- /hello/world:
-- RequestBody:
-- Format: ': * () ('[] *)
-- ContentType: ()
-- RequestType: 'POST
-- Response:
-- Format: ': * () ('[] *)
-- ContentType: ()
--
module Servant.Docs.Simple.Render
-- | Intermediate documentation structure, a hashmap of endpoints
--
-- API type:
--
--
-- type API = "users" :> ( "update" :> Response '[()] ()
-- :<|> "get" :> Response '[()] ()
-- )
--
--
-- Parsed into ApiDocs:
--
--
-- ApiDocs ( fromList [ ( "/users/update",
-- , Details (fromList ([ ( "Response"
-- , Details (fromList ([ ( "Format"
-- , Detail "': * () ('[] *)"
-- )
-- , ( "ContentType"
-- , Detail "()"
-- )
-- ]))
-- )
-- ]))
-- )
-- , ( "/users/get",
-- , Details (fromList ([ ( "Response"
-- , Details (fromList ([ ( "Format"
-- , Detail "': * () ('[] *)"
-- )
-- , ( "ContentType"
-- , Detail "()"
-- )
-- ]))
-- )
-- ]))
-- )
-- ])
--
--
-- For more examples reference Test.Servant.Docs.Simple.Samples
newtype ApiDocs
ApiDocs :: OMap Route Details -> ApiDocs
-- | Details of the Api Route
--
-- Examples
--
--
-- Authentication: true
--
--
-- Can be interpreted as a Parameter (Authentication) and a Detail
-- (true)
--
--
-- Response:
-- Format: ...
-- ContentType: ...
--
--
-- Can be interpreted as a Parameter (Response) and Details
-- (Format (...), ContentType (...))
data Details
-- | OMap of Parameter-Details
Details :: OMap Parameter Details -> Details
-- | Single Value
Detail :: Text -> Details
-- | Convert ApiDocs into different documentation formats
class Renderable a
render :: Renderable a => ApiDocs -> a
-- | Parameter names
type Parameter = Text
-- | Route representation
type Route = Text
-- | Conversion to JSON using Data.Aeson
newtype Json
Json :: Value -> Json
[getJson] :: Json -> Value
-- | Conversion to prettyprint
newtype Pretty ann
Pretty :: Doc ann -> Pretty ann
[getPretty] :: Pretty ann -> Doc ann
-- | Conversion to plaintext
newtype PlainText
PlainText :: Text -> PlainText
[getPlainText] :: PlainText -> Text
instance GHC.Show.Show Servant.Docs.Simple.Render.PlainText
instance GHC.Classes.Eq Servant.Docs.Simple.Render.PlainText
instance GHC.Show.Show Servant.Docs.Simple.Render.Json
instance GHC.Classes.Eq Servant.Docs.Simple.Render.Json
instance GHC.Show.Show Servant.Docs.Simple.Render.ApiDocs
instance GHC.Classes.Eq Servant.Docs.Simple.Render.ApiDocs
instance GHC.Show.Show Servant.Docs.Simple.Render.Details
instance GHC.Classes.Eq Servant.Docs.Simple.Render.Details
instance Servant.Docs.Simple.Render.Renderable Servant.Docs.Simple.Render.PlainText
instance Servant.Docs.Simple.Render.Renderable (Servant.Docs.Simple.Render.Pretty ann)
instance Servant.Docs.Simple.Render.Renderable Servant.Docs.Simple.Render.Json
instance Data.Aeson.Types.ToJSON.ToJSON Servant.Docs.Simple.Render.ApiDocs
instance Data.Aeson.Types.ToJSON.ToJSON Servant.Docs.Simple.Render.Details
-- | Parse Servant API into documentation
--
-- Example script
--
-- Generating the intermediate documentation structure
--
-- Parsing custom API type combinators
--
-- Example of parsing an API
--
-- API type
--
--
-- type API = "hello" :> "world" :> Request :> Response
-- type Request = ReqBody '[()] ()
-- type Response = Post '[()] ()
--
--
-- Intermediate structure
--
--
-- ApiDocs ( fromList [( "/hello/world",
-- , Details (fromList ([ ( "RequestBody"
-- , Details (fromList ([ ( "Format"
-- , Detail "': * () ('[] *)"
-- )
-- , ( "ContentType"
-- , Detail "()"
-- )
-- ]))
-- )
-- , ( "RequestType"
-- , Detail "'POST"
-- )
-- , ( "Response"
-- , Details (fromList ([ ( "Format"
-- , Detail "': * () ('[] *)"
-- )
-- , ( "ContentType"
-- , Detail "()"
-- )
-- ]))
-- )
-- ]))
-- )])
--
module Servant.Docs.Simple.Parse
-- | Folds an api endpoint into documentation
class HasDocumentApi api
-- | We use this to destructure the API type and convert it into
-- documentation
document :: HasDocumentApi api => Route -> [(Parameter, Details)] -> (Route, OMap Parameter Details)
-- | Flattens API into type level list of Endpoints
class HasParsable api
parse :: HasParsable api => ApiDocs
-- | Convert symbol to Text
symbolVal' :: forall n. KnownSymbol n => Text
-- | Convert parameter-value pairs to Details type
toDetails :: [(Text, Details)] -> Details
-- | Convert types to Text
typeText :: forall a. Typeable a => Text
instance forall a (api :: a) (b :: [a]). (Servant.Docs.Simple.Parse.HasDocumentApi api, Servant.Docs.Simple.Parse.HasCollatable b) => Servant.Docs.Simple.Parse.HasCollatable (api : b)
instance (Servant.Docs.Simple.Parse.HasDocumentApi b, GHC.TypeLits.KnownSymbol route) => Servant.Docs.Simple.Parse.HasDocumentApi (route Servant.API.Sub.:> b)
instance (Servant.Docs.Simple.Parse.HasDocumentApi b, GHC.TypeLits.KnownSymbol dRoute, Data.Typeable.Internal.Typeable t) => Servant.Docs.Simple.Parse.HasDocumentApi (Servant.API.Capture.Capture' m dRoute t Servant.API.Sub.:> b)
instance (Servant.Docs.Simple.Parse.HasDocumentApi b, GHC.TypeLits.KnownSymbol dRoute, Data.Typeable.Internal.Typeable t) => Servant.Docs.Simple.Parse.HasDocumentApi (Servant.API.Capture.CaptureAll dRoute t Servant.API.Sub.:> b)
instance Servant.Docs.Simple.Parse.HasDocumentApi b => Servant.Docs.Simple.Parse.HasDocumentApi (Network.HTTP.Types.Version.HttpVersion Servant.API.Sub.:> b)
instance Servant.Docs.Simple.Parse.HasDocumentApi b => Servant.Docs.Simple.Parse.HasDocumentApi (Servant.API.IsSecure.IsSecure Servant.API.Sub.:> b)
instance Servant.Docs.Simple.Parse.HasDocumentApi b => Servant.Docs.Simple.Parse.HasDocumentApi (Servant.API.RemoteHost.RemoteHost Servant.API.Sub.:> b)
instance (Servant.Docs.Simple.Parse.HasDocumentApi b, GHC.TypeLits.KnownSymbol desc) => Servant.Docs.Simple.Parse.HasDocumentApi (Servant.API.Description.Description desc Servant.API.Sub.:> b)
instance (Servant.Docs.Simple.Parse.HasDocumentApi b, GHC.TypeLits.KnownSymbol s) => Servant.Docs.Simple.Parse.HasDocumentApi (Servant.API.Description.Summary s Servant.API.Sub.:> b)
instance Servant.Docs.Simple.Parse.HasDocumentApi b => Servant.Docs.Simple.Parse.HasDocumentApi (Data.Vault.Lazy.Vault Servant.API.Sub.:> b)
instance (Servant.Docs.Simple.Parse.HasDocumentApi b, GHC.TypeLits.KnownSymbol realm, Data.Typeable.Internal.Typeable a) => Servant.Docs.Simple.Parse.HasDocumentApi (Servant.API.BasicAuth.BasicAuth realm a Servant.API.Sub.:> b)
instance (Servant.Docs.Simple.Parse.HasDocumentApi b, GHC.TypeLits.KnownSymbol token) => Servant.Docs.Simple.Parse.HasDocumentApi (Servant.API.Experimental.Auth.AuthProtect token Servant.API.Sub.:> b)
instance forall k b (ct :: GHC.Types.Symbol) (typ :: k) (m :: [*]). (Servant.Docs.Simple.Parse.HasDocumentApi b, GHC.TypeLits.KnownSymbol ct, Data.Typeable.Internal.Typeable typ) => Servant.Docs.Simple.Parse.HasDocumentApi (Servant.API.Header.Header' m ct typ Servant.API.Sub.:> b)
instance (Servant.Docs.Simple.Parse.HasDocumentApi b, GHC.TypeLits.KnownSymbol param) => Servant.Docs.Simple.Parse.HasDocumentApi (Servant.API.QueryParam.QueryFlag param Servant.API.Sub.:> b)
instance (Servant.Docs.Simple.Parse.HasDocumentApi b, GHC.TypeLits.KnownSymbol param, Data.Typeable.Internal.Typeable typ) => Servant.Docs.Simple.Parse.HasDocumentApi (Servant.API.QueryParam.QueryParam' m param typ Servant.API.Sub.:> b)
instance (Servant.Docs.Simple.Parse.HasDocumentApi b, GHC.TypeLits.KnownSymbol param, Data.Typeable.Internal.Typeable typ) => Servant.Docs.Simple.Parse.HasDocumentApi (Servant.API.QueryParam.QueryParams param typ Servant.API.Sub.:> b)
instance (Servant.Docs.Simple.Parse.HasDocumentApi b, Data.Typeable.Internal.Typeable ct, Data.Typeable.Internal.Typeable typ) => Servant.Docs.Simple.Parse.HasDocumentApi (Servant.API.ReqBody.ReqBody' m ct typ Servant.API.Sub.:> b)
instance (Servant.Docs.Simple.Parse.HasDocumentApi b, Data.Typeable.Internal.Typeable ct, Data.Typeable.Internal.Typeable typ) => Servant.Docs.Simple.Parse.HasDocumentApi (Servant.API.Stream.StreamBody' m ct typ Servant.API.Sub.:> b)
instance forall k1 (m :: k1) (ct :: [*]) typ (s :: GHC.Types.Nat). (Data.Typeable.Internal.Typeable m, Data.Typeable.Internal.Typeable ct, Data.Typeable.Internal.Typeable typ) => Servant.Docs.Simple.Parse.HasDocumentApi (Servant.API.Verbs.Verb m s ct typ)
instance Servant.Docs.Simple.Parse.HasCollatable (Servant.API.TypeLevel.Endpoints a) => Servant.Docs.Simple.Parse.HasParsable a
instance Servant.Docs.Simple.Parse.HasParsable Servant.API.Empty.EmptyAPI
instance Servant.Docs.Simple.Parse.HasCollatable '[]
-- | Parse and render an API type, write documentation to file, stdout
--
-- Example script
--
-- Writing documentation to file
--
-- With the following language extensions
--
--
-- DataKinds
-- TypeApplications
-- TypeOperators
--
--
-- Using this script
--
--
-- module Main where
--
-- import Servant.API ((:>), Post, ReqBody)
-- import Servant.Docs.Simple (writeDocsJson, writeDocsPlainText)
--
-- -- Our API type
-- type API = "hello" :> "world" :> Request :> Response
-- type Request = ReqBody '[()] ()
-- type Response = Post '[()] ()
--
-- main :: IO ()
-- main = do
-- -- Writes to the file $PWD/docsJson
-- writeDocsJson @API "docs.json"
--
-- -- Writes to the file $PWD/docsPlainText
-- writeDocsPlainText @API "docs.txt"
--
--
-- Expected Output
--
-- Files should be generated relative to $PWD
--
--
-- $ ls | grep docs
-- docs.json
-- docs.txt
--
--
-- docs.json
--
--
-- {
-- "/hello/world": {
-- "Response": {
-- "Format": "': * () ('[] *)",
-- "ContentType": "()"
-- },
-- "RequestType": "'POST",
-- "RequestBody": {
-- "Format": "': * () ('[] *)",
-- "ContentType": "()"
-- }
-- }
-- }
--
--
-- docs.txt
--
--
-- /hello/world:
-- RequestBody:
-- Format: ': * () ('[] *)
-- ContentType: ()
-- RequestType: 'POST
-- Response:
-- Format: ': * () ('[] *)
-- ContentType: ()
--
module Servant.Docs.Simple
-- | Convert API type into PlainText format
document :: forall api. HasParsable api => PlainText
-- | Convert API type into specified formats
documentWith :: forall api a. (HasParsable api, Renderable a) => a
-- | Write documentation as JSON to stdout
stdoutJson :: forall api. HasParsable api => IO ()
-- | Write documentation as PlainText to stdout
stdoutPlainText :: forall api. HasParsable api => IO ()
-- | Write documentation as JSON to file
writeDocsJson :: forall api. HasParsable api => FilePath -> IO ()
-- | Write documentation as PlainText to file
writeDocsPlainText :: forall api. HasParsable api => FilePath -> IO ()