Maintainer | Nickolay Kudasov <nickolay@getshoptv.com> |
---|---|
Stability | experimental |
Safe Haskell | None |
Language | Haskell2010 |
Data.Swagger.Schema
Contents
Description
Types and functions for working with Swagger schema.
- class ToSchema a where
- declareSchema :: ToSchema a => proxy a -> Declare (Definitions Schema) Schema
- declareSchemaRef :: ToSchema a => proxy a -> Declare (Definitions Schema) (Referenced Schema)
- toSchema :: ToSchema a => proxy a -> Schema
- toSchemaRef :: ToSchema a => proxy a -> Referenced Schema
- schemaName :: ToSchema a => proxy a -> Maybe Text
- toInlinedSchema :: ToSchema a => proxy a -> Schema
- genericDeclareNamedSchema :: forall a proxy. (Generic a, GToSchema (Rep a)) => SchemaOptions -> proxy a -> Declare (Definitions Schema) NamedSchema
- genericDeclareSchema :: (Generic a, GToSchema (Rep a)) => SchemaOptions -> proxy a -> Declare (Definitions Schema) Schema
- genericToNamedSchemaBoundedIntegral :: forall a d f proxy. (Bounded a, Integral a, Generic a, Rep a ~ D1 d f, Datatype d) => SchemaOptions -> proxy a -> NamedSchema
- toSchemaBoundedIntegral :: forall a proxy. (Bounded a, Integral a) => proxy a -> Schema
- paramSchemaToNamedSchema :: forall a d f proxy. (ToParamSchema a, Generic a, Rep a ~ D1 d f, Datatype d) => SchemaOptions -> proxy a -> NamedSchema
- paramSchemaToSchema :: forall a proxy. ToParamSchema a => proxy a -> Schema
- passwordSchema :: Schema
- binarySchema :: Schema
- byteSchema :: Schema
- sketchSchema :: ToJSON a => a -> Schema
- sketchStrictSchema :: ToJSON a => a -> Schema
- inlineNonRecursiveSchemas :: Data s => Definitions Schema -> s -> s
- inlineAllSchemas :: Data s => Definitions Schema -> s -> s
- inlineSchemas :: Data s => [Text] -> Definitions Schema -> s -> s
- inlineSchemasWhen :: Data s => (Text -> Bool) -> Definitions Schema -> s -> s
- data SchemaOptions = SchemaOptions {}
- defaultSchemaOptions :: SchemaOptions
Encoding
Convert a type into
.Schema
An example type and instance:
{-# LANGUAGE OverloadedStrings #-} -- allows to writeText
literals {-# LANGUAGE OverloadedLists #-} -- allows to writeMap
andHashMap
as lists import Control.Lens import Data.Proxy import Data.Swagger data Coord = Coord { x :: Double, y :: Double } instance ToSchema Coord where declareNamedSchema _ = do doubleSchema <- declareSchemaRef (Proxy :: Proxy Double) return $ NamedSchema (Just "Coord") $ mempty & type_ .~ SwaggerObject & properties .~ [ ("x", doubleSchema) , ("y", doubleSchema) ] & required .~ [ "x", "y" ]
Instead of manually writing your
instance you can
use a default generic implementation of ToSchema
.declareNamedSchema
To do that, simply add deriving
clause to your datatype
and declare a Generic
instance for your datatype without
giving definition for ToSchema
.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
Methods
declareNamedSchema :: proxy a -> Declare (Definitions Schema) 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).
declareNamedSchema :: (Generic a, GToSchema (Rep a)) => proxy a -> Declare (Definitions Schema) 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
declareSchema :: ToSchema a => proxy a -> Declare (Definitions Schema) Schema #
Convert a type into a schema and declare all used schema definitions.
declareSchemaRef :: ToSchema a => proxy a -> Declare (Definitions Schema) (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
returns a reference, a corresponding schema
will be declared (regardless of whether it is recusive or not).declareSchemaRef
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\"}"
schemaName :: ToSchema a => proxy a -> Maybe Text #
Get type's schema name according to its
instance.ToSchema
>>>
schemaName (Proxy :: Proxy Int)
Nothing
>>>
schemaName (Proxy :: Proxy UTCTime)
Just "UTCTime"
toInlinedSchema :: ToSchema a => proxy a -> Schema #
Convert a type into a schema without references.
>>>
encode $ toInlinedSchema (Proxy :: Proxy [Day])
"{\"items\":{\"example\":\"2016-07-22\",\"format\":\"date\",\"type\":\"string\"},\"type\":\"array\"}"
WARNING:
will produce infinite schema
when inlining recursive schemas.toInlinedSchema
Generic schema encoding
genericDeclareNamedSchema :: forall a proxy. (Generic a, GToSchema (Rep a)) => SchemaOptions -> proxy a -> Declare (Definitions Schema) NamedSchema #
A configurable generic
creator.
This function applied to NamedSchema
is used as the default for defaultSchemaOptions
when the type is an instance of declareNamedSchema
.Generic
genericDeclareSchema :: (Generic a, GToSchema (Rep a)) => SchemaOptions -> proxy a -> Declare (Definitions Schema) Schema #
A configurable generic
creator.Schema
genericToNamedSchemaBoundedIntegral :: forall a d f proxy. (Bounded a, Integral a, Generic a, Rep a ~ D1 d f, Datatype d) => SchemaOptions -> proxy a -> NamedSchema #
toSchemaBoundedIntegral :: forall a proxy. (Bounded a, Integral a) => proxy a -> Schema #
paramSchemaToNamedSchema :: forall a d f proxy. (ToParamSchema a, Generic a, Rep a ~ D1 d f, Datatype d) => SchemaOptions -> proxy a -> NamedSchema #
Lift a plain
into a model ParamSchema
.NamedSchema
paramSchemaToSchema :: forall a proxy. ToParamSchema a => proxy a -> Schema #
Lift a plain
into a model ParamSchema
.Schema
Schema templates
Default schema for password string.
"password"
format is used to hint UIs the input needs to be obscured.
binarySchema :: Schema #
Default schema for binary data (any sequence of octets).
byteSchema :: Schema #
Default schema for binary data (base64 encoded).
Sketching Schema
s using ToJSON
Schema
ToJSON
sketchSchema :: ToJSON a => a -> Schema #
Make an unrestrictive sketch of a
based on a Schema
instance.
Produced schema can be used for further refinement.ToJSON
>>>
encode $ sketchSchema "hello"
"{\"example\":\"hello\",\"type\":\"string\"}"
>>>
encode $ sketchSchema (1, 2, 3)
"{\"example\":[1,2,3],\"items\":{\"type\":\"number\"},\"type\":\"array\"}"
>>>
encode $ 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
>>>
encode $ sketchSchema (Person "Jack" 25)
"{\"required\":[\"age\",\"name\"],\"properties\":{\"age\":{\"type\":\"number\"},\"name\":{\"type\":\"string\"}},\"example\":{\"age\":25,\"name\":\"Jack\"},\"type\":\"object\"}"
sketchStrictSchema :: ToJSON a => a -> Schema #
Make a restrictive sketch of a
based on a Schema
instance.
Produced schema uses as much constraints as possible.ToJSON
>>>
encode $ sketchStrictSchema "hello"
"{\"maxLength\":5,\"pattern\":\"hello\",\"minLength\":5,\"type\":\"string\",\"enum\":[\"hello\"]}"
>>>
encode $ sketchStrictSchema (1, 2, 3)
"{\"minItems\":3,\"uniqueItems\":true,\"items\":[{\"maximum\":1,\"minimum\":1,\"multipleOf\":1,\"type\":\"number\",\"enum\":[1]},{\"maximum\":2,\"minimum\":2,\"multipleOf\":2,\"type\":\"number\",\"enum\":[2]},{\"maximum\":3,\"minimum\":3,\"multipleOf\":3,\"type\":\"number\",\"enum\":[3]}],\"maxItems\":3,\"type\":\"array\",\"enum\":[[1,2,3]]}"
>>>
encode $ sketchStrictSchema ("Jack", 25)
"{\"minItems\":2,\"uniqueItems\":true,\"items\":[{\"maxLength\":4,\"pattern\":\"Jack\",\"minLength\":4,\"type\":\"string\",\"enum\":[\"Jack\"]},{\"maximum\":25,\"minimum\":25,\"multipleOf\":25,\"type\":\"number\",\"enum\":[25]}],\"maxItems\":2,\"type\":\"array\",\"enum\":[[\"Jack\",25]]}"
>>>
data Person = Person { name :: String, age :: Int } deriving (Generic)
>>>
instance ToJSON Person
>>>
encode $ sketchStrictSchema (Person "Jack" 25)
"{\"required\":[\"age\",\"name\"],\"properties\":{\"age\":{\"maximum\":25,\"minimum\":25,\"multipleOf\":25,\"type\":\"number\",\"enum\":[25]},\"name\":{\"maxLength\":4,\"pattern\":\"Jack\",\"minLength\":4,\"type\":\"string\",\"enum\":[\"Jack\"]}},\"maxProperties\":2,\"minProperties\":2,\"type\":\"object\",\"enum\":[{\"age\":25,\"name\":\"Jack\"}]}"
Inlining Schema
s
Schema
inlineNonRecursiveSchemas :: Data s => Definitions Schema -> s -> s #
Inline all non-recursive schemas for which the definition
can be found in
.Definitions
inlineAllSchemas :: Data s => Definitions Schema -> s -> s #
Inline all schema references for which the definition
can be found in
.Definitions
WARNING:
will produce infinite schemas
when inlining recursive schemas.inlineAllSchemas
inlineSchemas :: Data s => [Text] -> Definitions Schema -> 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:
will produce infinite schemas
when inlining recursive schemas.inlineSchemas
inlineSchemasWhen :: Data s => (Text -> Bool) -> Definitions Schema -> 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:
will produce infinite schemas
when inlining recursive schemas.inlineSchemasWhen
Generic encoding configuration
data SchemaOptions #
Options that specify how to encode your type to Swagger schema.
Constructors
SchemaOptions | |
Fields
|
defaultSchemaOptions :: SchemaOptions #
Default encoding
.SchemaOptions
SchemaOptions
{fieldLabelModifier
= id ,constructorTagModifier
= id ,datatypeNameModifier
= id ,allNullaryToStringTag
= True ,unwrapUnaryRecords
= False }