Data.Swagger.Build.Api

Construction of Data.Swagger.Model.Api values. For example:

declare "http://petstore.swagger.wordnik.com/api" "1.2" $ do
   apiVersion "1.0.0"
   resourcePath "/store"
   model foo
   model bar
   produces "application/json"
   produces "text/html"
   produces "text/plain"
   api "/store/order/{orderId}" $ do
       operation "GET" "foo" $ do
           summary "give me some foo"
           notes   "but only the good one"
           returns (ref foo)
           parameter Header "type" (string $ enum ["bar", "baz"]) $ do
               description "specifies the type of foo"
               optional
           parameter Query "format" (string $ enum ["plain", "html"]) $
               description "output format"
           parameter Query "size" (int32 $ min 1 . max 100 . def 10) $
               description "amount of foo"
           produces "application/json"
           produces "text/html"
           response 200 "OK" (model foo)
           response 400 "Bad Request" end
       operation "POST" "foo" $ do
           summary "something else"
           deprecated

data types

Re-exports

data ApiDecl

Cf. API Declaration

Instances

Show ApiDecl

ToJSON ApiDecl

data API

Cf. API Object

Instances

Show API

ToJSON API

data Operation

Cf. Operation Object

Instances

Show Operation

ToJSON Operation

data Parameter

Cf. Parameter Object

Instances

Show Parameter

ToJSON Parameter

data ParamType

Constructors

Path

Query

Body

Header

Form

Instances

Eq ParamType

Show ParamType

ToJSON ParamType

data Response

Cf. Response Message Object

Instances

Show Response

ToJSON Response

data Model

Cf. Model Object

Instances

Show Model

ToJSON Model

data Property

Cf. Property Object

Instances

Show Property

ToJSON Property

data DataType

Instances

Show DataType

data Primitive a

Cf. Primitive Types

Instances

Show a => Show (Primitive a)

data Items a

Instances

Show a => Show (Items a)

primitive construction

int32 :: (Primitive Int32 -> Primitive Int32) -> DataType

int32' :: DataType

int64 :: (Primitive Int64 -> Primitive Int64) -> DataType

int64' :: DataType

float :: (Primitive Float -> Primitive Float) -> DataType

float' :: DataType

bool :: (Primitive Bool -> Primitive Bool) -> DataType

bool' :: DataType

double :: (Primitive Double -> Primitive Double) -> DataType

double' :: DataType

string :: (Primitive String -> Primitive String) -> DataType

string' :: DataType

bytes :: (Primitive String -> Primitive String) -> DataType

bytes' :: DataType

date :: (Primitive UTCTime -> Primitive UTCTime) -> DataType

date' :: DataType

dateTime :: (Primitive UTCTime -> Primitive UTCTime) -> DataType

dateTime' :: DataType

primitive modifiers

def :: a -> Primitive a -> Primitive a

Default value of some primitive type.

enum :: [a] -> Primitive a -> Primitive a

Enumerate valid values of some primitive type.

min :: a -> Primitive a -> Primitive a

Minimum value of some primitive type.

max :: a -> Primitive a -> Primitive a

Maximum value of some primitive type.

data-type constructors

ref :: Model -> DataType

array :: DataType -> DataType

unique :: DataType -> DataType

Specify that array elements are unique.

builder types

type ApiDeclSt = Common `["produces", "consumes", "models", "authorisations"]` ApiDecl

type ApiDeclBuilder = State ApiDeclSt ()

type ApiSt = Common `["description"]` API

type ApiBuilder = State ApiSt ()

type OperationSt = Common `["produces", "consumes", "authorisations"]` Operation

type OperationBuilder = State OperationSt ()

type ParameterSt = Common `["description", "required"]` Parameter

type ParameterBuilder = State ParameterSt ()

type ResponseSt = Common `["models"]` Response

type ResponseBuilder = State ResponseSt ()

type ModelSt = Common `["description"]` Model

type ModelBuilder = State ModelSt ()

type PropertySt = Common `["description", "required"]` Property

type PropertyBuilder = State PropertySt ()

API declaration

declare :: Text -> Text -> ApiDeclBuilder -> ApiDecl

Create an API declaration given a base URL, a swagger version, and other API declaration values.

apiVersion :: Text -> ApiDeclBuilder

resourcePath :: Text -> ApiDeclBuilder

api :: Text -> ApiBuilder -> ApiDeclBuilder

Add one API object to an API declaration given some path and other API object values.

model :: Elem "models" f => Model -> State (Common f a) ()

operation

operation :: Text -> Text -> OperationBuilder -> ApiBuilder

Add one operation object to an API object given an HTTP method, a nickname and other operation specific values.

returns :: DataType -> OperationBuilder

parameter :: ParamType -> Text -> DataType -> ParameterBuilder -> OperationBuilder

Add one parameter object to an operation object given the ParamType, the parameter name and the actual data-type plus some other parameter values.

file :: Text -> ParameterBuilder -> OperationBuilder

Like parameter but specific for file uploads.

body :: DataType -> ParameterBuilder -> OperationBuilder

Like parameter but specific for request body parameters. Sets ParamType to Body and uses as name "body" which is the only valid name for request bodies.

summary :: Text -> OperationBuilder

notes :: Text -> OperationBuilder

response :: Int -> Text -> ResponseBuilder -> OperationBuilder

Add one response message object to an operation given a status code and some message plus response message specific values.

produces :: Elem "produces" f => Text -> State (Common f a) ()

authorisation :: Elem "authorisations" f => Auth -> State (Common f a) ()

data Auth

Constructors

Basic

ApiKey

OAuth2 Scope

None

parameter

multiple :: ParameterBuilder

model

defineModel :: ModelId -> ModelBuilder -> Model

Construct a complex data-type (aka "Model") given some identifier and model-specific values.

property :: PropertyName -> DataType -> PropertyBuilder -> ModelBuilder

Add a property to a model given a name, type and other propertu values.

children :: PropertyName -> [Model] -> ModelBuilder

Specify a sub-typing relationship for a model by given a "discriminator" property name and all sub-types.

various

description :: Elem "description" f => Text -> State (Common f a) ()

optional :: Elem "required" f => State (Common f a) ()

consumes :: Elem "consumes" f => Text -> State (Common f a) ()

deprecated :: OperationBuilder

end :: Monad m => m ()

If cases where no build steps are provided but a builder is required end can be used, e.g. defineModel "Foo" end