Data.Swagger.Schema.Internal

Documentation

type NamedSchema = (Maybe String, Schema)

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

unnamed :: Schema -> NamedSchema

named :: String -> Schema -> 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 as list

import Control.Lens

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

instance ToSchema Coord where
  toNamedSchema = (Just "Coord", mempty
     & schemaType .~ SchemaObject
     & 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 toNamedSchema.

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

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

toNamedSchema :: proxy a -> NamedSchema

Convert a type into an optionally named schema.

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

>>> toSchema (Proxy :: Proxy ZonedTime) ^. schemaFormat
Just "yyyy-mm-ddThh:MM:ss(Z|+hh:MM)"

ToSchema NominalDiffTime

ToSchema Day

>>> toSchema (Proxy :: Proxy Day) ^. schemaFormat
Just "yyyy-mm-dd"

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)

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

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

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

Convert a type into a schema.

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

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

class GToSchema f where

Methods

gtoNamedSchema :: SchemaOptions -> proxy f -> Schema -> NamedSchema

Instances

GToSchema U1

ToSchema c => GToSchema (K1 i 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.

gtoSchema :: GToSchema f => SchemaOptions -> proxy f -> Schema -> Schema

timeNamedSchema :: String -> String -> NamedSchema

data SchemaOptions

Options that specify how to encode your type to Swagger schema.

Constructors

SchemaOptions

Fields

fieldLabelModifier :: String -> String

Function applied to field labels. Handy for removing common record prefixes for example.

constructorTagModifier :: String -> String

Function applied to constructor tags which could be handy for lower-casing them for example.

datatypeNameModifier :: String -> String

Function applied to datatype name.

allNullaryToStringTag :: Bool

If True the constructors of a datatype, with all nullary constructors, will be encoded to a string enumeration schema with the constructor tags as possible values.

useReferences :: Bool

If True direct subschemas will be referenced if possible (rather than inlined). Note that this option does not influence nested schemas, e.g. for these types

data Object = Object String deriving Generic
instance ToSchema Object

newtype Objects = Objects [Object] deriving Generic
instance ToSchema Objects where
   toNamedSchema = genericToNamedSchema defaultSchemaOptions
     { useReferences = False }

Schema for Objects will not inline Object schema because it is nested in a [] schema.

unwrapUnaryRecords :: Bool

Hide the field name when a record constructor has only one field, like a newtype.

defaultSchemaOptions :: SchemaOptions

Default encoding SchemaOptions.

SchemaOptions
{ fieldLabelModifier     = id
, constructorTagModifier = id
, datatypeNameModifier   = id
, allNullaryToStringTag  = True
, useReferences          = True
, unwrapUnaryRecords     = False
}

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

Default schema for Bounded, Integral types.

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.

genericToSchema :: (Generic a, GToSchema (Rep a)) => SchemaOptions -> proxy a -> Schema

A configurable generic Schema creator.

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

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

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

nullarySchema :: Schema

gtoSchemaRef :: GToSchema f => SchemaOptions -> proxy f -> Referenced Schema

appendItem :: Referenced Schema -> Maybe SchemaItems -> Maybe SchemaItems

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

type AllNullary = All

class GSumToSchema f where

Methods

gsumToSchema :: SchemaOptions -> proxy f -> Schema -> (AllNullary, Schema)

Instances

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

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

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

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

gsumConToSchema :: forall c f proxy. Constructor c => Bool -> Referenced Schema -> SchemaOptions -> proxy (C1 c f) -> Schema -> (AllNullary, Schema)

data Proxy2 a b

Constructors

Proxy2

data Proxy3 a b c

Constructors

Proxy3