Data.API.Doc

Documentation

callHtml :: DocInfo -> Dict -> Call -> String

Generate a web page documenting a Call

dirHtml :: DocInfo -> Dict -> [Call] -> String

Generate a web page documenting all the Calls in a web application

data Call

Documents a single method call on a resource in a web application

Constructors

Call

Fields

• call_http_method :: HTTPMethod

  HTTP method being documented

• call_path :: [String]

  Relative URL path of the resource

• call_description :: String

  Free-form text description

• call_auth_required :: Bool

  Does the call require authentication?

• call_headers :: [Header]

  HTTP headers relevant to the call

• call_body :: Maybe (APIType, String)

  Type and example of request body

• call_params :: [Param]

  Query parameters relevant to the call

• call_views :: [View]

  Available views of the result data

• call_samples :: [Sample]

  Example responses

Instances

Show Call

Methods

showsPrec :: Int -> Call -> ShowS

show :: Call -> String

showList :: [Call] -> ShowS

data Header

Documents a HTTP header that may be supplied to a Call

Constructors

Header

Fields

• header_name :: String

  Header name

• header_expl :: String

  Example value for header

• header_desc :: String

  Free-form text description

• header_type :: APIType

  Type of data in header

• header_required :: Bool

  Is including the header with the request mandatory?

Instances

Show Header

Methods

showsPrec :: Int -> Header -> ShowS

show :: Header -> String

showList :: [Header] -> ShowS

data Param

Documents a URL query parameter that may be included with a Call

Constructors

Param

Fields

• param_name :: String

  Parameter name

• param_expl :: String

  Example value for parameter

• param_desc :: String

  Free-form text description

• param_type :: Either String APIType

  Type of data in the parameter

• param_required :: Bool

  Is including the parameter mandatory?

Instances

Show Param

Methods

showsPrec :: Int -> Param -> ShowS

show :: Param -> String

showList :: [Param] -> ShowS

data View

Documents a specific view of the result data available in a Call

Constructors

View

Fields

• view_id :: String

  View name

• view_type :: APIType

  Type of result data returned

• view_doc :: String

  Free-form text description

• view_params :: [Param]

  Query parameters that may be supplied for this view

Instances

Show View

Methods

showsPrec :: Int -> View -> ShowS

show :: View -> String

showList :: [View] -> ShowS

data Sample

Example response data from a Call

Constructors

Sample

Fields

• sample_status :: StatusCode

  HTTP status code for this example response

• sample_type :: Body APIType

  Type of example response

• sample_response :: Maybe String

  Content of response, or Nothing for empty response

Instances

Show Sample

Methods

showsPrec :: Int -> Sample -> ShowS

show :: Sample -> String

showList :: [Sample] -> ShowS

data Body t

Type for Sample response body, parameterised by possible JSON types

Constructors

EmptyBody

An empty response

JSONBody t

A JSON response of the given type

OtherBody String

A non-empty, non-JSON response

Instances

Functor Body

Methods

fmap :: (a -> b) -> Body a -> Body b

(<$) :: a -> Body b -> Body a

Show t => Show (Body t)

Methods

showsPrec :: Int -> Body t -> ShowS

show :: Body t -> String

showList :: [Body t] -> ShowS

data DocInfo

Record of arguments that must be supplied to generate HTML documentation for a Call

Constructors

DocInfo

Fields

• doc_info_call_url :: HTTPMethod -> [String] -> URL

  URL for individual call documentation from the index

• doc_info_type_url :: TypeName -> URL

  URL for documentation of an API type

type URL = String

type HTTPMethod = String

type StatusCode = Int

renderAPIType :: DocInfo -> APIType -> String

renderBodyType :: DocInfo -> Body APIType -> String

mk_link :: URL -> String -> String