| 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
class ToSchema a where Source #
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 = 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 ToSchemadeclareNamedSchema
To do that, simply add deriving clause to your datatype
and declare a GenericToSchemadeclareNamedSchema
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 Source #
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 Source #
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 Source #
Convert a type into a schema and declare all used schema definitions.
declareSchemaRef :: ToSchema a => proxy a -> Declare (Definitions Schema) (Referenced Schema) Source #
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
toSchema :: ToSchema a => proxy a -> Schema Source #
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 Source #
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 Source #
Get type's schema name according to its ToSchema
>>>schemaName (Proxy :: Proxy Int)Nothing
>>>schemaName (Proxy :: Proxy UTCTime)Just "UTCTime"
toInlinedSchema :: ToSchema a => proxy a -> Schema Source #
Convert a type into a schema without references.
>>>encode $ toInlinedSchema (Proxy :: Proxy [Day])"{\"items\":{\"format\":\"date\",\"type\":\"string\"},\"type\":\"array\"}"
WARNING: toInlinedSchema
Generic schema encoding
genericDeclareNamedSchema :: forall a proxy. (Generic a, GToSchema (Rep a)) => SchemaOptions -> proxy a -> Declare (Definitions Schema) NamedSchema Source #
A configurable generic NamedSchemadefaultSchemaOptionsdeclareNamedSchemaGeneric
genericDeclareSchema :: (Generic a, GToSchema (Rep a)) => SchemaOptions -> proxy a -> Declare (Definitions Schema) Schema Source #
A configurable generic Schema
genericToNamedSchemaBoundedIntegral :: forall a d f proxy. (Bounded a, Integral a, Generic a, Rep a ~ D1 d f, Datatype d) => SchemaOptions -> proxy a -> NamedSchema Source #
paramSchemaToNamedSchema :: forall a d f proxy. (ToParamSchema a, Generic a, Rep a ~ D1 d f, Datatype d) => SchemaOptions -> proxy a -> NamedSchema Source #
Lift a plain ParamSchemaNamedSchema
paramSchemaToSchema :: forall a proxy. ToParamSchema a => proxy a -> Schema Source #
Lift a plain ParamSchemaSchema
Schema templates
passwordSchema :: Schema Source #
Default schema for password string.
"password" format is used to hint UIs the input needs to be obscured.
binarySchema :: Schema Source #
Default schema for binary data (any sequence of octets).
byteSchema :: Schema Source #
Default schema for binary data (base64 encoded).
Sketching SchemaToJSON
SchemaToJSONsketchSchema :: ToJSON a => a -> Schema Source #
Make an unrestrictive sketch of a SchemaToJSON
>>>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 Source #
Make a restrictive sketch of a SchemaToJSON
>>>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
SchemainlineNonRecursiveSchemas :: Data s => Definitions Schema -> s -> s Source #
Inline all non-recursive schemas for which the definition
can be found in Definitions
inlineAllSchemas :: Data s => Definitions Schema -> s -> s Source #
Inline all schema references for which the definition
can be found in Definitions
WARNING: inlineAllSchemas
inlineSchemas :: Data s => [Text] -> Definitions Schema -> s -> s Source #
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
inlineSchemasWhen :: Data s => (Text -> Bool) -> Definitions Schema -> s -> s Source #
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
Generic encoding configuration
data SchemaOptions Source #
Options that specify how to encode your type to Swagger schema.
Constructors
| SchemaOptions | |
Fields
| |
defaultSchemaOptions :: SchemaOptions Source #
Default encoding SchemaOptions
SchemaOptions{fieldLabelModifier= id ,constructorTagModifier= id ,datatypeNameModifier= id ,allNullaryToStringTag= True ,unwrapUnaryRecords= False }