-- 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.4.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 tree 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 :: [(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
Details :: [(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 markdown
newtype Markdown
Markdown :: Text -> Markdown
[getMarkdown] :: Markdown -> Text
-- | Conversion to prettyprint
newtype Pretty
Pretty :: Doc Ann -> Pretty
[getPretty] :: Pretty -> Doc Ann
-- | Conversion to plaintext
newtype PlainText
PlainText :: Text -> PlainText
[getPlainText] :: PlainText -> Text
instance GHC.Show.Show Servant.Docs.Simple.Render.Details
instance GHC.Classes.Eq Servant.Docs.Simple.Render.Details
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.Json
instance GHC.Classes.Eq Servant.Docs.Simple.Render.Json
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.Markdown
instance GHC.Classes.Eq Servant.Docs.Simple.Render.Markdown
instance Servant.Docs.Simple.Render.Renderable Servant.Docs.Simple.Render.Markdown
instance Servant.Docs.Simple.Render.Renderable Servant.Docs.Simple.Render.PlainText
instance Servant.Docs.Simple.Render.Renderable Servant.Docs.Simple.Render.Pretty
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 HasParsableEndpoint e
-- | We use this to destructure the API type and convert it into
-- documentation
parseEndpoint :: HasParsableEndpoint e => Route -> [(Parameter, Details)] -> (Route, [(Parameter, Details)])
-- | Flattens API into type level list of Endpoints
class HasParsableApi api
parseApi :: HasParsableApi api => ApiDocs
-- | Convert symbol to Text
symbolVal' :: forall n. KnownSymbol n => Text
-- | Convert types to Text
typeText :: forall a. Typeable a => Text
-- | Converts type-level list of types to Text. If the type variable
-- doesn't correspond to type level list, the result is the same as
-- calling typeText.
--
--
-- >>> typeListText @'[JSON,PlainText]
-- "[JSON,PlainText]"
--
typeListText :: forall a. Typeable a => Text
instance forall a (e :: a) (b :: [a]). (Servant.Docs.Simple.Parse.HasParsableEndpoint e, Servant.Docs.Simple.Parse.HasCollatable b) => Servant.Docs.Simple.Parse.HasCollatable (e : b)
instance (Servant.Docs.Simple.Parse.HasParsableEndpoint b, GHC.TypeLits.KnownSymbol route) => Servant.Docs.Simple.Parse.HasParsableEndpoint (route Servant.API.Sub.:> b)
instance (Servant.Docs.Simple.Parse.HasParsableEndpoint b, GHC.TypeLits.KnownSymbol dRoute, Data.Typeable.Internal.Typeable t) => Servant.Docs.Simple.Parse.HasParsableEndpoint (Servant.API.Capture.Capture' m dRoute t Servant.API.Sub.:> b)
instance (Servant.Docs.Simple.Parse.HasParsableEndpoint b, GHC.TypeLits.KnownSymbol dRoute, Data.Typeable.Internal.Typeable t) => Servant.Docs.Simple.Parse.HasParsableEndpoint (Servant.API.Capture.CaptureAll dRoute t Servant.API.Sub.:> b)
instance Servant.Docs.Simple.Parse.HasParsableEndpoint b => Servant.Docs.Simple.Parse.HasParsableEndpoint (Network.HTTP.Types.Version.HttpVersion Servant.API.Sub.:> b)
instance Servant.Docs.Simple.Parse.HasParsableEndpoint b => Servant.Docs.Simple.Parse.HasParsableEndpoint (Servant.API.IsSecure.IsSecure Servant.API.Sub.:> b)
instance Servant.Docs.Simple.Parse.HasParsableEndpoint b => Servant.Docs.Simple.Parse.HasParsableEndpoint (Servant.API.RemoteHost.RemoteHost Servant.API.Sub.:> b)
instance (Servant.Docs.Simple.Parse.HasParsableEndpoint b, GHC.TypeLits.KnownSymbol desc) => Servant.Docs.Simple.Parse.HasParsableEndpoint (Servant.API.Description.Description desc Servant.API.Sub.:> b)
instance (Servant.Docs.Simple.Parse.HasParsableEndpoint b, GHC.TypeLits.KnownSymbol s) => Servant.Docs.Simple.Parse.HasParsableEndpoint (Servant.API.Description.Summary s Servant.API.Sub.:> b)
instance Servant.Docs.Simple.Parse.HasParsableEndpoint b => Servant.Docs.Simple.Parse.HasParsableEndpoint (Data.Vault.Lazy.Vault Servant.API.Sub.:> b)
instance (Servant.Docs.Simple.Parse.HasParsableEndpoint b, GHC.TypeLits.KnownSymbol realm, Data.Typeable.Internal.Typeable a) => Servant.Docs.Simple.Parse.HasParsableEndpoint (Servant.API.BasicAuth.BasicAuth realm a Servant.API.Sub.:> b)
instance (Servant.Docs.Simple.Parse.HasParsableEndpoint b, GHC.TypeLits.KnownSymbol token) => Servant.Docs.Simple.Parse.HasParsableEndpoint (Servant.API.Experimental.Auth.AuthProtect token Servant.API.Sub.:> b)
instance (Servant.Docs.Simple.Parse.HasParsableEndpoint b, GHC.TypeLits.KnownSymbol ct, Data.Typeable.Internal.Typeable typ) => Servant.Docs.Simple.Parse.HasParsableEndpoint (Servant.API.Header.Header' m ct typ Servant.API.Sub.:> b)
instance (Servant.Docs.Simple.Parse.HasParsableEndpoint b, GHC.TypeLits.KnownSymbol param) => Servant.Docs.Simple.Parse.HasParsableEndpoint (Servant.API.QueryParam.QueryFlag param Servant.API.Sub.:> b)
instance (Servant.Docs.Simple.Parse.HasParsableEndpoint b, GHC.TypeLits.KnownSymbol param, Data.Typeable.Internal.Typeable typ) => Servant.Docs.Simple.Parse.HasParsableEndpoint (Servant.API.QueryParam.QueryParam' m param typ Servant.API.Sub.:> b)
instance (Servant.Docs.Simple.Parse.HasParsableEndpoint b, GHC.TypeLits.KnownSymbol param, Data.Typeable.Internal.Typeable typ) => Servant.Docs.Simple.Parse.HasParsableEndpoint (Servant.API.QueryParam.QueryParams param typ Servant.API.Sub.:> b)
instance (Servant.Docs.Simple.Parse.HasParsableEndpoint b, Data.Typeable.Internal.Typeable ct, Data.Typeable.Internal.Typeable typ) => Servant.Docs.Simple.Parse.HasParsableEndpoint (Servant.API.ReqBody.ReqBody' m ct typ Servant.API.Sub.:> b)
instance (Servant.Docs.Simple.Parse.HasParsableEndpoint b, Data.Typeable.Internal.Typeable ct, Data.Typeable.Internal.Typeable typ) => Servant.Docs.Simple.Parse.HasParsableEndpoint (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.HasParsableEndpoint (Servant.API.Verbs.Verb m s ct typ)
instance Servant.Docs.Simple.Parse.HasCollatable (Servant.API.TypeLevel.Endpoints a) => Servant.Docs.Simple.Parse.HasParsableApi a
instance Servant.Docs.Simple.Parse.HasParsableApi 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/docs.json
-- writeDocsJson @API "docs.json"
--
-- -- Writes to the file $PWD/docs.txt
-- 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. HasParsableApi api => PlainText
-- | Convert API type into specified formats
documentWith :: forall api a. (HasParsableApi api, Renderable a) => a
-- | Write documentation as JSON to stdout
stdoutJson :: forall api. HasParsableApi api => IO ()
-- | Write documentation as Markdown to stdout
stdoutMarkdown :: forall api. HasParsableApi api => IO ()
-- | Write documentation as PlainText to stdout
stdoutPlainText :: forall api. HasParsableApi api => IO ()
-- | Write documentation as JSON to file
writeDocsJson :: forall api. HasParsableApi api => FilePath -> IO ()
-- | Write documentation as Markdown to file
writeDocsMarkdown :: forall api. HasParsableApi api => FilePath -> IO ()
-- | Write documentation as PlainText to file
writeDocsPlainText :: forall api. HasParsableApi api => FilePath -> IO ()