Data.Swagger.Internal.Schema

Documentation

type NamedSchema = (Maybe Text, Schema)

A Schema with an optional name. This name can be used in references.

type Definitions = HashMap Text Schema

Schema definitions, a mapping from schema name to Schema.

unnamed :: Schema -> NamedSchema

named :: Text -> Schema -> NamedSchema

plain :: Schema -> Declare Definitions NamedSchema

unname :: NamedSchema -> NamedSchema

rename :: Maybe Text -> NamedSchema -> NamedSchema

class ToSchema a where

Convert a type into Schema.

An example type and instance:

{-# LANGUAGE OverloadedStrings #-}   -- allows to write Text literals
{-# LANGUAGE OverloadedLists #-}     -- allows to write Map and HashMap as lists

import Control.Lens

data Coord = Coord { x :: Double, y :: Double }

instance ToSchema Coord where
  declareNamedSchema = pure (Just "Coord", schema)
   where
     schema = mempty
       & schemaType .~ SwaggerObject
       & schemaProperties .~
           [ ("x", toSchemaRef (Proxy :: Proxy Double))
           , ("y", toSchemaRef (Proxy :: Proxy Double))
           ]
       & schemaRequired .~ [ "x", "y" ]

Instead of manually writing your ToSchema instance you can use a default generic implementation of declareNamedSchema.

To do that, simply add deriving Generic clause to your datatype and declare a ToSchema instance for your datatype without giving definition for declareNamedSchema.

For instance, the previous example can be simplified into this:

{-# LANGUAGE DeriveGeneric #-}

import GHC.Generics (Generic)

data Coord = Coord { x :: Double, y :: Double } deriving Generic

instance ToSchema Coord

Minimal complete definition

Nothing

Methods

declareNamedSchema :: proxy a -> Declare Definitions NamedSchema

Convert a type into an optionally named schema together with all used definitions. Note that the schema itself is included in definitions only if it is recursive (and thus needs its definition in scope).

Instances

ToSchema Bool

ToSchema Char

ToSchema Double

ToSchema Float

ToSchema Int

ToSchema Int8

ToSchema Int16

ToSchema Int32

ToSchema Int64

ToSchema Integer

ToSchema Word

ToSchema Word8

ToSchema Word16

ToSchema Word32

ToSchema Word64

ToSchema String

ToSchema ()

ToSchema Scientific

ToSchema Text

ToSchema UTCTime

>>> toSchema (Proxy :: Proxy UTCTime) ^. schemaFormat
Just "yyyy-mm-ddThh:MM:ssZ"

ToSchema Text

ToSchema All

ToSchema Any

ToSchema IntSet

ToSchema LocalTime

>>> toSchema (Proxy :: Proxy LocalTime) ^. schemaFormat
Just "yyyy-mm-ddThh:MM:ss"

ToSchema ZonedTime

Format "date" corresponds to yyyy-mm-ddThh:MM:ss(Z|+hh:MM) format.

ToSchema NominalDiffTime

ToSchema Day

Format "date" corresponds to yyyy-mm-dd format.

ToSchema a => ToSchema [a]

ToSchema a => ToSchema (Maybe a)

ToSchema a => ToSchema (Dual a)

ToSchema a => ToSchema (Sum a)

ToSchema a => ToSchema (Product a)

ToSchema a => ToSchema (First a)

ToSchema a => ToSchema (Last a)

ToSchema a => ToSchema (IntMap a)

NOTE: This schema does not account for the uniqueness of keys.

ToSchema a => ToSchema (Set a)

ToSchema a => ToSchema (HashSet a)

(ToSchema a, ToSchema b) => ToSchema (Either a b)

(ToSchema a, ToSchema b) => ToSchema (a, b)

ToSchema a => ToSchema (HashMap String a)

ToSchema a => ToSchema (HashMap Text a)

ToSchema a => ToSchema (HashMap Text a)

ToSchema a => ToSchema (Map String a)

ToSchema a => ToSchema (Map Text a)

ToSchema a => ToSchema (Map Text a)

(ToSchema a, ToSchema b, ToSchema c) => ToSchema (a, b, c)

(ToSchema a, ToSchema b, ToSchema c, ToSchema d) => ToSchema (a, b, c, d)

(ToSchema a, ToSchema b, ToSchema c, ToSchema d, ToSchema e) => ToSchema (a, b, c, d, e)

(ToSchema a, ToSchema b, ToSchema c, ToSchema d, ToSchema e, ToSchema f) => ToSchema (a, b, c, d, e, f)

(ToSchema a, ToSchema b, ToSchema c, ToSchema d, ToSchema e, ToSchema f, ToSchema g) => ToSchema (a, b, c, d, e, f, g)

declareSchema :: ToSchema a => proxy a -> Declare Definitions Schema

Convert a type into a schema and declare all used schema definitions.

toNamedSchema :: ToSchema a => proxy a -> NamedSchema

Convert a type into an optionally named schema.

>>> encode <$> toNamedSchema (Proxy :: Proxy String)
(Nothing,"{\"type\":\"string\"}")

>>> encode <$> toNamedSchema (Proxy :: Proxy Day)
(Just "Day","{\"format\":\"date\",\"type\":\"string\"}")

schemaName :: ToSchema a => proxy a -> Maybe Text

Get type's schema name according to its ToSchema instance.

>>> schemaName (Proxy :: Proxy Int)
Nothing

>>> schemaName (Proxy :: Proxy UTCTime)
Just "UTCTime"

toSchema :: ToSchema a => proxy a -> Schema

Convert a type into a schema.

>>> encode $ toSchema (Proxy :: Proxy Int8)
"{\"maximum\":127,\"minimum\":-128,\"type\":\"integer\"}"

>>> encode $ toSchema (Proxy :: Proxy [Day])
"{\"items\":{\"$ref\":\"#/definitions/Day\"},\"type\":\"array\"}"

toSchemaRef :: ToSchema a => proxy a -> Referenced Schema

Convert a type into a referenced schema if possible. Only named schemas can be referenced, nameless schemas are inlined.

>>> encode $ toSchemaRef (Proxy :: Proxy Integer)
"{\"type\":\"integer\"}"

>>> encode $ toSchemaRef (Proxy :: Proxy Day)
"{\"$ref\":\"#/definitions/Day\"}"

declareSchemaRef :: ToSchema a => proxy a -> Declare Definitions (Referenced Schema)

Convert a type into a referenced schema if possible and declare all used schema definitions. Only named schemas can be referenced, nameless schemas are inlined.

Schema definitions are typically declared for every referenced schema. If declareSchemaRef returns a reference, a corresponding schema will be declared (regardless of whether it is recusive or not).

inlineSchemasWhen :: Data s => (Text -> Bool) -> Definitions -> s -> s

Inline any referenced schema if its name satisfies given predicate.

NOTE: if a referenced schema is not found in definitions the predicate is ignored and schema stays referenced.

WARNING: inlineSchemasWhen will produce infinite schemas when inlining recursive schemas.

inlineSchemas :: Data s => [Text] -> Definitions -> s -> s

Inline any referenced schema if its name is in the given list.

NOTE: if a referenced schema is not found in definitions it stays referenced even if it appears in the list of names.

WARNING: inlineSchemas will produce infinite schemas when inlining recursive schemas.

inlineAllSchemas :: Data s => Definitions -> s -> s

Inline all schema references for which the definition can be found in Definitions.

WARNING: inlineAllSchemas will produce infinite schemas when inlining recursive schemas.

toInlinedSchema :: ToSchema a => proxy a -> Schema

Convert a type into a schema without references.

>>> encode $ toInlinedSchema (Proxy :: Proxy [Day])
"{\"items\":{\"format\":\"date\",\"type\":\"string\"},\"type\":\"array\"}"

WARNING: toInlinedSchema will produce infinite schema when inlining recursive schemas.

inlineNonRecursiveSchemas :: Data s => Definitions -> s -> s

Inline all non-recursive schemas for which the definition can be found in Definitions.

class GToSchema f where

Methods

gdeclareNamedSchema :: SchemaOptions -> proxy f -> Schema -> Declare Definitions NamedSchema

Instances

GToSchema U1

ToSchema c => GToSchema (K1 i c)

ToSchema c => GToSchema (K1 i (Maybe c))

(GSumToSchema (* -> *) f, GSumToSchema (* -> *) g) => GToSchema ((:+:) f g)

(GToSchema f, GToSchema g) => GToSchema ((:*:) f g)

(Datatype d, GToSchema f) => GToSchema (D1 d f)

(Selector s, GToSchema f) => GToSchema (C1 c (S1 s f))

Single field constructor.

GToSchema f => GToSchema (C1 c f)

(Selector s, GToSchema f) => GToSchema (S1 s f)

Record fields.

(Selector s, ToSchema c) => GToSchema (S1 s (K1 i (Maybe c)))

Optional record fields.

timeSchema :: Text -> Schema

toSchemaBoundedIntegral :: forall a proxy. (Bounded a, Integral a) => proxy a -> Schema

Default schema for Bounded, Integral types.

>>> encode $ toSchemaBoundedIntegral (Proxy :: Proxy Int16)
"{\"maximum\":32767,\"minimum\":-32768,\"type\":\"integer\"}"

genericToNamedSchemaBoundedIntegral :: forall a d f proxy. (Bounded a, Integral a, Generic a, Rep a ~ D1 d f, Datatype d) => SchemaOptions -> proxy a -> NamedSchema

Default generic named schema for Bounded, Integral types.

genericDeclareSchema :: (Generic a, GToSchema (Rep a)) => SchemaOptions -> proxy a -> Declare Definitions Schema

A configurable generic Schema creator.

genericDeclareNamedSchema :: forall a proxy. (Generic a, GToSchema (Rep a)) => SchemaOptions -> proxy a -> Declare Definitions NamedSchema

A configurable generic NamedSchema creator. This function applied to defaultSchemaOptions is used as the default for declareNamedSchema when the type is an instance of Generic.

gdatatypeSchemaName :: forall proxy d. Datatype d => SchemaOptions -> proxy d -> Maybe Text

paramSchemaToNamedSchema :: forall a d f proxy. (ToParamSchema a, Generic a, Rep a ~ D1 d f, Datatype d) => SchemaOptions -> proxy a -> NamedSchema

Lift a plain ParamSchema into a model NamedSchema.

paramSchemaToSchema :: forall a proxy. ToParamSchema a => proxy a -> Schema

Lift a plain ParamSchema into a model Schema.

nullarySchema :: Schema

gtoNamedSchema :: GToSchema f => SchemaOptions -> proxy f -> NamedSchema

gdeclareSchema :: GToSchema f => SchemaOptions -> proxy f -> Declare Definitions Schema

gdeclareSchemaRef :: GToSchema a => SchemaOptions -> proxy a -> Declare Definitions (Referenced Schema)

appendItem :: Referenced Schema -> Maybe (SwaggerItems Schema) -> Maybe (SwaggerItems Schema)

withFieldSchema :: forall proxy s f. (Selector s, GToSchema f) => SchemaOptions -> proxy s f -> Bool -> Schema -> Declare Definitions Schema

type AllNullary = All

class GSumToSchema f where

Methods

gsumToSchema :: SchemaOptions -> proxy f -> Schema -> WriterT AllNullary (Declare Definitions) Schema

Instances

(GSumToSchema (* -> *) f, GSumToSchema (* -> *) g) => GSumToSchema (* -> *) ((:+:) f g)

Constructor c => GSumToSchema (* -> *) (C1 c U1)

(Constructor c, Selector s, GToSchema f) => GSumToSchema (* -> *) (C1 c (S1 s f))

(Constructor c, GToSchema f) => GSumToSchema (* -> *) (C1 c f)

gsumConToSchema :: forall c f proxy. (GToSchema (C1 c f), Constructor c) => SchemaOptions -> proxy (C1 c f) -> Schema -> Declare Definitions Schema

data Proxy2 a b

Constructors

Proxy2

data Proxy3 a b c

Constructors

Proxy3