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
import Data.Proxy
import Data.OpenApi

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

instance ToSchema Coord where
  declareNamedSchema _ = do
    doubleSchema <- declareSchemaRef (Proxy :: Proxy Double)
    return $ NamedSchema (Just "Coord") $ mempty
      & type_ ?~ OpenApiObject
      & properties .~
          [ ("x", doubleSchema)
          , ("y", doubleSchema)
          ]
      & required .~ [ "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

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

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).

Convert a type into a schema.

>>> BSL.putStrLn $ encodePretty $ toSchema (Proxy :: Proxy Int8)
{
    "maximum": 127,
    "minimum": -128,
    "type": "integer"
}

>>> BSL.putStrLn $ encodePretty $ toSchema (Proxy :: Proxy [Day])
{
    "items": {
        "$ref": "#/components/schemas/Day"
    },
    "type": "array"
}

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

>>> BSL.putStrLn $ encodePretty $ toSchemaRef (Proxy :: Proxy Integer)
{
    "type": "integer"
}

>>> BSL.putStrLn $ encodePretty $ toSchemaRef (Proxy :: Proxy Day)
{
    "$ref": "#/components/schemas/Day"
}

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

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

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

Convert a type into a schema without references.

>>> BSL.putStrLn $ encodePretty $ toInlinedSchema (Proxy :: Proxy [Day])
{
    "items": {
        "example": "2016-07-22",
        "format": "date",
        "type": "string"
    },
    "type": "array"
}

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

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.

Default implementation will use the name from Typeable instance, including concrete instantioations of type variables.

For example:

>>> _namedSchemaName $ undeclare $ genericDeclareNamedSchema defaultSchemaOptions (Proxy :: Proxy (Either Int Bool))
Just "Either_Int_Bool"

A configurable generic Schema creator.

Declare a named schema for a newtype wrapper.

Derive a Generic-based name for a datatype and assign it to a given Schema.

Default generic named schema for Bounded, Integral types.

Default schema for Bounded, Integral types.

>>> BSL.putStrLn $ encodePretty $ toSchemaBoundedIntegral (Proxy :: Proxy Int16)
{
    "maximum": 32767,
    "minimum": -32768,
    "type": "integer"
}

Declare Schema for a mapping with Bounded Enum keys. This makes a much more useful schema when there aren't many options for key values.

>>> data ButtonState = Neutral | Focus | Active | Hover | Disabled deriving (Show, Bounded, Enum, Generic)
>>> instance ToJSON ButtonState
>>> instance ToSchema ButtonState
>>> instance ToJSONKey ButtonState where toJSONKey = toJSONKeyText (T.pack . show)
>>> type ImageUrl = T.Text
>>> BSL.putStrLn $ encodePretty $ toSchemaBoundedEnumKeyMapping (Proxy :: Proxy (Map ButtonState ImageUrl))
{
    "properties": {
        "Active": {
            "type": "string"
        },
        "Disabled": {
            "type": "string"
        },
        "Focus": {
            "type": "string"
        },
        "Hover": {
            "type": "string"
        },
        "Neutral": {
            "type": "string"
        }
    },
    "type": "object"
}

Note: this is only useful when key is encoded with ToJSONKeyText. If it is encoded with ToJSONKeyValue then a regular schema for [(key, value)] is used.

A Schema for a mapping with Bounded Enum keys. This makes a much more useful schema when there aren't many options for key values.

>>> data ButtonState = Neutral | Focus | Active | Hover | Disabled deriving (Show, Bounded, Enum, Generic)
>>> instance ToJSON ButtonState
>>> instance ToSchema ButtonState
>>> instance ToJSONKey ButtonState where toJSONKey = toJSONKeyText (T.pack . show)
>>> type ImageUrl = T.Text
>>> BSL.putStrLn $ encodePretty $ toSchemaBoundedEnumKeyMapping (Proxy :: Proxy (Map ButtonState ImageUrl))
{
    "properties": {
        "Active": {
            "type": "string"
        },
        "Disabled": {
            "type": "string"
        },
        "Focus": {
            "type": "string"
        },
        "Hover": {
            "type": "string"
        },
        "Neutral": {
            "type": "string"
        }
    },
    "type": "object"
}

Note: this is only useful when key is encoded with ToJSONKeyText. If it is encoded with ToJSONKeyValue then a regular schema for [(key, value)] is used.

Construct NamedSchema usinng ToParamSchema.

Construct Schema usinng ToParamSchema.

Make an unrestrictive sketch of a Schema based on a ToJSON instance. Produced schema can be used for further refinement.

>>> BSL.putStrLn $ encodePretty $ sketchSchema "hello"
{
    "example": "hello",
    "type": "string"
}

>>> BSL.putStrLn $ encodePretty $ sketchSchema (1, 2, 3)
{
    "example": [
        1,
        2,
        3
    ],
    "items": {
        "type": "number"
    },
    "type": "array"
}

>>> BSL.putStrLn $ encodePretty $ sketchSchema ("Jack", 25)
{
    "example": [
        "Jack",
        25
    ],
    "items": [
        {
            "type": "string"
        },
        {
            "type": "number"
        }
    ],
    "type": "array"
}

>>> data Person = Person { name :: String, age :: Int } deriving (Generic)
>>> instance ToJSON Person
>>> BSL.putStrLn $ encodePretty $ sketchSchema (Person "Jack" 25)
{
    "example": {
        "age": 25,
        "name": "Jack"
    },
    "properties": {
        "age": {
            "type": "number"
        },
        "name": {
            "type": "string"
        }
    },
    "required": [
        "age",
        "name"
    ],
    "type": "object"
}

Make a restrictive sketch of a Schema based on a ToJSON instance. Produced schema uses as much constraints as possible.

>>> BSL.putStrLn $ encodePretty $ sketchStrictSchema "hello"
{
    "enum": [
        "hello"
    ],
    "maxLength": 5,
    "minLength": 5,
    "pattern": "hello",
    "type": "string"
}

>>> BSL.putStrLn $ encodePretty $ sketchStrictSchema (1, 2, 3)
{
    "enum": [
        [
            1,
            2,
            3
        ]
    ],
    "items": [
        {
            "enum": [
                1
            ],
            "maximum": 1,
            "minimum": 1,
            "multipleOf": 1,
            "type": "number"
        },
        {
            "enum": [
                2
            ],
            "maximum": 2,
            "minimum": 2,
            "multipleOf": 2,
            "type": "number"
        },
        {
            "enum": [
                3
            ],
            "maximum": 3,
            "minimum": 3,
            "multipleOf": 3,
            "type": "number"
        }
    ],
    "maxItems": 3,
    "minItems": 3,
    "type": "array",
    "uniqueItems": true
}

>>> BSL.putStrLn $ encodePretty $ sketchStrictSchema ("Jack", 25)
{
    "enum": [
        [
            "Jack",
            25
        ]
    ],
    "items": [
        {
            "enum": [
                "Jack"
            ],
            "maxLength": 4,
            "minLength": 4,
            "pattern": "Jack",
            "type": "string"
        },
        {
            "enum": [
                25
            ],
            "maximum": 25,
            "minimum": 25,
            "multipleOf": 25,
            "type": "number"
        }
    ],
    "maxItems": 2,
    "minItems": 2,
    "type": "array",
    "uniqueItems": true
}

>>> data Person = Person { name :: String, age :: Int } deriving (Generic)
>>> instance ToJSON Person
>>> BSL.putStrLn $ encodePretty $ sketchStrictSchema (Person "Jack" 25)
{
    "enum": [
        {
            "age": 25,
            "name": "Jack"
        }
    ],
    "maxProperties": 2,
    "minProperties": 2,
    "properties": {
        "age": {
            "enum": [
                25
            ],
            "maximum": 25,
            "minimum": 25,
            "multipleOf": 25,
            "type": "number"
        },
        "name": {
            "enum": [
                "Jack"
            ],
            "maxLength": 4,
            "minLength": 4,
            "pattern": "Jack",
            "type": "string"
        }
    },
    "required": [
        "age",
        "name"
    ],
    "type": "object"
}

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

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

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

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.

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.

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

Default encoding SchemaOptions.

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

Convert Options to SchemaOptions.

Specifically the following fields get copied:

• fieldLabelModifier
• constructorTagModifier
• allNullaryToStringTag
• unwrapUnaryRecords

Note that these fields have no effect on SchemaOptions:

• omitNothingFields
• tagSingleConstructors

The rest is defined as in defaultSchemaOptions.

Since: 2.2.1