| Safe Haskell | Safe-Inferred |
|---|---|
| Language | Haskell2010 |
Data.Swagger.Internal.Schema
Synopsis
- unnamed :: Schema -> NamedSchema
- named :: Text -> Schema -> NamedSchema
- plain :: Schema -> Declare (Definitions Schema) NamedSchema
- unname :: NamedSchema -> NamedSchema
- rename :: Maybe Text -> NamedSchema -> NamedSchema
- class ToSchema a where
- declareNamedSchema :: Proxy a -> Declare (Definitions Schema) NamedSchema
- declareSchema :: ToSchema a => Proxy a -> Declare (Definitions Schema) Schema
- toNamedSchema :: ToSchema a => Proxy a -> NamedSchema
- schemaName :: ToSchema a => Proxy a -> Maybe Text
- toSchema :: ToSchema a => Proxy a -> Schema
- toSchemaRef :: ToSchema a => Proxy a -> Referenced Schema
- declareSchemaRef :: ToSchema a => Proxy a -> Declare (Definitions Schema) (Referenced Schema)
- inlineSchemasWhen :: Data s => (Text -> Bool) -> Definitions Schema -> s -> s
- inlineSchemas :: Data s => [Text] -> Definitions Schema -> s -> s
- inlineAllSchemas :: Data s => Definitions Schema -> s -> s
- toInlinedSchema :: ToSchema a => Proxy a -> Schema
- inlineNonRecursiveSchemas :: Data s => Definitions Schema -> s -> s
- binarySchema :: Schema
- byteSchema :: Schema
- passwordSchema :: Schema
- sketchSchema :: ToJSON a => a -> Schema
- sketchStrictSchema :: ToJSON a => a -> Schema
- class GToSchema (f :: * -> *) where
- gdeclareNamedSchema :: SchemaOptions -> Proxy f -> Schema -> Declare (Definitions Schema) NamedSchema
- timeSchema :: Text -> Schema
- type family ToSchemaByteStringError bs where ...
- toSchemaBoundedIntegral :: forall a. (Bounded a, Integral a) => Proxy a -> Schema
- genericToNamedSchemaBoundedIntegral :: forall a d f. (Bounded a, Integral a, Generic a, Rep a ~ D1 d f, Datatype d) => SchemaOptions -> Proxy a -> NamedSchema
- genericDeclareNamedSchemaNewtype :: forall a d c s i inner. (Generic a, Datatype d, Rep a ~ D1 d (C1 c (S1 s (K1 i inner)))) => SchemaOptions -> (Proxy inner -> Declare (Definitions Schema) Schema) -> Proxy a -> Declare (Definitions Schema) NamedSchema
- declareSchemaBoundedEnumKeyMapping :: forall map key value. (Bounded key, Enum key, ToJSONKey key, ToSchema key, ToSchema value) => Proxy (map key value) -> Declare (Definitions Schema) Schema
- toSchemaBoundedEnumKeyMapping :: forall map key value. (Bounded key, Enum key, ToJSONKey key, ToSchema key, ToSchema value) => Proxy (map key value) -> Schema
- genericDeclareSchema :: (Generic a, GToSchema (Rep a), TypeHasSimpleShape a "genericDeclareSchemaUnrestricted") => SchemaOptions -> Proxy a -> Declare (Definitions Schema) Schema
- genericDeclareNamedSchema :: (Generic a, GToSchema (Rep a), TypeHasSimpleShape a "genericDeclareNamedSchemaUnrestricted") => SchemaOptions -> Proxy a -> Declare (Definitions Schema) NamedSchema
- genericDeclareSchemaUnrestricted :: (Generic a, GToSchema (Rep a)) => SchemaOptions -> Proxy a -> Declare (Definitions Schema) Schema
- genericDeclareNamedSchemaUnrestricted :: forall a. (Generic a, GToSchema (Rep a)) => SchemaOptions -> Proxy a -> Declare (Definitions Schema) NamedSchema
- genericNameSchema :: forall a d f. (Generic a, Rep a ~ D1 d f, Datatype d) => SchemaOptions -> Proxy a -> Schema -> NamedSchema
- gdatatypeSchemaName :: forall d. Datatype d => SchemaOptions -> Proxy d -> Maybe Text
- paramSchemaToNamedSchema :: (ToParamSchema a, Generic a, Rep a ~ D1 d f, Datatype d) => SchemaOptions -> Proxy a -> NamedSchema
- paramSchemaToSchema :: ToParamSchema a => Proxy a -> Schema
- nullarySchema :: Schema
- gtoNamedSchema :: GToSchema f => SchemaOptions -> Proxy f -> NamedSchema
- gdeclareSchema :: GToSchema f => SchemaOptions -> Proxy f -> Declare (Definitions Schema) Schema
- gdeclareSchemaRef :: GToSchema a => SchemaOptions -> Proxy a -> Declare (Definitions Schema) (Referenced Schema)
- appendItem :: Referenced Schema -> Maybe (SwaggerItems 'SwaggerKindSchema) -> Maybe (SwaggerItems 'SwaggerKindSchema)
- withFieldSchema :: forall proxy s f. (Selector s, GToSchema f) => SchemaOptions -> proxy s f -> Bool -> Schema -> Declare (Definitions Schema) Schema
- gdeclareNamedSumSchema :: GSumToSchema f => SchemaOptions -> Proxy f -> Schema -> Declare (Definitions Schema) NamedSchema
- type AllNullary = All
- class GSumToSchema (f :: * -> *) where
- gsumToSchema :: SchemaOptions -> Proxy f -> Schema -> WriterT AllNullary (Declare (Definitions Schema)) Schema
- gsumConToSchemaWith :: forall c f. (GToSchema (C1 c f), Constructor c) => Referenced Schema -> SchemaOptions -> Proxy (C1 c f) -> Schema -> Schema
- gsumConToSchema :: (GToSchema (C1 c f), Constructor c) => SchemaOptions -> Proxy (C1 c f) -> Schema -> Declare (Definitions Schema) Schema
- data Proxy2 a b = Proxy2
- data Proxy3 a b c = Proxy3
Documentation
unnamed :: Schema -> NamedSchema Source #
plain :: Schema -> Declare (Definitions Schema) NamedSchema Source #
unname :: NamedSchema -> NamedSchema Source #
rename :: Maybe Text -> NamedSchema -> NamedSchema Source #
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
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 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
Minimal complete definition
Nothing
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).
default declareNamedSchema :: (Generic a, GToSchema (Rep a), TypeHasSimpleShape a "genericDeclareNamedSchemaUnrestricted") => Proxy a -> Declare (Definitions Schema) NamedSchema Source #
Instances
declareSchema :: ToSchema a => Proxy a -> Declare (Definitions Schema) Schema Source #
Convert a type into a schema and declare all used schema definitions.
toNamedSchema :: ToSchema a => Proxy a -> NamedSchema Source #
Convert a type into an optionally named schema.
>>>toNamedSchema (Proxy :: Proxy String) ^. nameNothing>>>encode (toNamedSchema (Proxy :: Proxy String) ^. schema)"{\"type\":\"string\"}"
>>>toNamedSchema (Proxy :: Proxy Day) ^. nameJust "Day">>>encode (toNamedSchema (Proxy :: Proxy Day) ^. schema)"{\"example\":\"2016-07-22\",\"format\":\"date\",\"type\":\"string\"}"
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"
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\"}"
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
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
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
inlineAllSchemas :: Data s => Definitions Schema -> s -> s Source #
Inline all schema references for which the definition
can be found in Definitions
WARNING: inlineAllSchemas
toInlinedSchema :: ToSchema a => Proxy a -> Schema Source #
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: toInlinedSchema
inlineNonRecursiveSchemas :: Data s => Definitions Schema -> s -> s Source #
Inline all non-recursive schemas for which the definition
can be found in Definitions
binarySchema :: Schema Source #
Default schema for binary data (any sequence of octets).
byteSchema :: Schema Source #
Default schema for binary data (base64 encoded).
passwordSchema :: Schema Source #
Default schema for password string.
"password" format is used to hint UIs the input needs to be obscured.
sketchSchema :: 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
sketchStrictSchema :: ToJSON a => a -> Schema Source #
Make a restrictive sketch of a SchemaToJSON
>>>encode $ sketchStrictSchema "hello""{\"enum\":[\"hello\"],\"maxLength\":5,\"minLength\":5,\"pattern\":\"hello\",\"type\":\"string\"}"
>>>encode $ 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}"
>>>encode $ 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
class GToSchema (f :: * -> *) where Source #
Methods
gdeclareNamedSchema :: SchemaOptions -> Proxy f -> Schema -> Declare (Definitions Schema) NamedSchema Source #
Instances
timeSchema :: Text -> Schema Source #
type family ToSchemaByteStringError bs where ... Source #
genericToNamedSchemaBoundedIntegral :: forall a d f. (Bounded a, Integral a, Generic a, Rep a ~ D1 d f, Datatype d) => SchemaOptions -> Proxy a -> NamedSchema Source #
genericDeclareNamedSchemaNewtype Source #
Arguments
| :: forall a d c s i inner. (Generic a, Datatype d, Rep a ~ D1 d (C1 c (S1 s (K1 i inner)))) | |
| => SchemaOptions | How to derive the name. |
| -> (Proxy inner -> Declare (Definitions Schema) Schema) | How to create a schema for the wrapped type. |
| -> Proxy a | |
| -> Declare (Definitions Schema) NamedSchema |
Declare a named schema for a newtype wrapper.
declareSchemaBoundedEnumKeyMapping :: forall map key value. (Bounded key, Enum key, ToJSONKey key, ToSchema key, ToSchema value) => Proxy (map key value) -> Declare (Definitions Schema) Schema Source #
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>>>encode $ toSchemaBoundedEnumKeyMapping (Proxy :: Proxy (Map ButtonState ImageUrl))"{\"properties\":{\"Neutral\":{\"type\":\"string\"},\"Focus\":{\"type\":\"string\"},\"Active\":{\"type\":\"string\"},\"Hover\":{\"type\":\"string\"},\"Disabled\":{\"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.
toSchemaBoundedEnumKeyMapping :: forall map key value. (Bounded key, Enum key, ToJSONKey key, ToSchema key, ToSchema value) => Proxy (map key value) -> Schema Source #
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>>>encode $ toSchemaBoundedEnumKeyMapping (Proxy :: Proxy (Map ButtonState ImageUrl))"{\"properties\":{\"Neutral\":{\"type\":\"string\"},\"Focus\":{\"type\":\"string\"},\"Active\":{\"type\":\"string\"},\"Hover\":{\"type\":\"string\"},\"Disabled\":{\"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.
genericDeclareSchema :: (Generic a, GToSchema (Rep a), TypeHasSimpleShape a "genericDeclareSchemaUnrestricted") => SchemaOptions -> Proxy a -> Declare (Definitions Schema) Schema Source #
A configurable generic Schema
genericDeclareNamedSchema :: (Generic a, GToSchema (Rep a), TypeHasSimpleShape a "genericDeclareNamedSchemaUnrestricted") => SchemaOptions -> Proxy a -> Declare (Definitions Schema) NamedSchema Source #
A configurable generic NamedSchemadefaultSchemaOptionsdeclareNamedSchemaGeneric
genericDeclareSchemaUnrestricted :: (Generic a, GToSchema (Rep a)) => SchemaOptions -> Proxy a -> Declare (Definitions Schema) Schema Source #
A configurable generic Schema
Unlike genericDeclareSchema also works for mixed sum types.
Use with care since some Swagger tools do not support well schemas for mixed sum types.
genericDeclareNamedSchemaUnrestricted :: forall a. (Generic a, GToSchema (Rep a)) => SchemaOptions -> Proxy a -> Declare (Definitions Schema) NamedSchema Source #
A configurable generic NamedSchema
Unlike genericDeclareNamedSchema also works for mixed sum types.
Use with care since some Swagger tools do not support well schemas for mixed sum types.
genericNameSchema :: forall a d f. (Generic a, Rep a ~ D1 d f, Datatype d) => SchemaOptions -> Proxy a -> Schema -> NamedSchema Source #
gdatatypeSchemaName :: forall d. Datatype d => SchemaOptions -> Proxy d -> Maybe Text Source #
paramSchemaToNamedSchema :: (ToParamSchema a, Generic a, Rep a ~ D1 d f, Datatype d) => SchemaOptions -> Proxy a -> NamedSchema Source #
Lift a plain ParamSchemaNamedSchema
paramSchemaToSchema :: ToParamSchema a => Proxy a -> Schema Source #
Lift a plain ParamSchemaSchema
gtoNamedSchema :: GToSchema f => SchemaOptions -> Proxy f -> NamedSchema Source #
gdeclareSchema :: GToSchema f => SchemaOptions -> Proxy f -> Declare (Definitions Schema) Schema Source #
gdeclareSchemaRef :: GToSchema a => SchemaOptions -> Proxy a -> Declare (Definitions Schema) (Referenced Schema) Source #
appendItem :: Referenced Schema -> Maybe (SwaggerItems 'SwaggerKindSchema) -> Maybe (SwaggerItems 'SwaggerKindSchema) Source #
withFieldSchema :: forall proxy s f. (Selector s, GToSchema f) => SchemaOptions -> proxy s f -> Bool -> Schema -> Declare (Definitions Schema) Schema Source #
gdeclareNamedSumSchema :: GSumToSchema f => SchemaOptions -> Proxy f -> Schema -> Declare (Definitions Schema) NamedSchema Source #
type AllNullary = All Source #
class GSumToSchema (f :: * -> *) where Source #
Methods
gsumToSchema :: SchemaOptions -> Proxy f -> Schema -> WriterT AllNullary (Declare (Definitions Schema)) Schema Source #
Instances
| (GSumToSchema f, GSumToSchema g) => GSumToSchema (f :+: g) Source # | |
Defined in Data.Swagger.Internal.Schema Methods gsumToSchema :: SchemaOptions -> Proxy (f :+: g) -> Schema -> WriterT AllNullary (Declare (Definitions Schema)) Schema Source # | |
| (Constructor c, Selector s, GToSchema f) => GSumToSchema (C1 c (S1 s f)) Source # | |
Defined in Data.Swagger.Internal.Schema Methods gsumToSchema :: SchemaOptions -> Proxy (C1 c (S1 s f)) -> Schema -> WriterT AllNullary (Declare (Definitions Schema)) Schema Source # | |
| Constructor c => GSumToSchema (C1 c (U1 :: Type -> Type)) Source # | |
Defined in Data.Swagger.Internal.Schema Methods gsumToSchema :: SchemaOptions -> Proxy (C1 c U1) -> Schema -> WriterT AllNullary (Declare (Definitions Schema)) Schema Source # | |
| (Constructor c, GToSchema f) => GSumToSchema (C1 c f) Source # | |
Defined in Data.Swagger.Internal.Schema Methods gsumToSchema :: SchemaOptions -> Proxy (C1 c f) -> Schema -> WriterT AllNullary (Declare (Definitions Schema)) Schema Source # | |
gsumConToSchemaWith :: forall c f. (GToSchema (C1 c f), Constructor c) => Referenced Schema -> SchemaOptions -> Proxy (C1 c f) -> Schema -> Schema Source #
gsumConToSchema :: (GToSchema (C1 c f), Constructor c) => SchemaOptions -> Proxy (C1 c f) -> Schema -> Declare (Definitions Schema) Schema Source #
>>>import Data.Swagger>>>import Data.Aeson (encode)>>>import Data.Aeson.Types (toJSONKeyText)