Data.Swagger.Schema

Types and functions for working with Swagger schema.

Encoding

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)

type NamedSchema = (Maybe String, Schema)

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

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.

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

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

Generic schema encoding

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.

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.

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

Default schema for Bounded, Integral types.

Generic encoding configuration

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
}