swagger2-2.1.4.1: Swagger 2.0 data model

Maintainer | Nickolay Kudasov <nickolay@getshoptv.com>
Stability | experimental
Safe Haskell | None
Language | Haskell2010

Data.Swagger.ParamSchema

Contents

- Encoding
- Generic schema encoding
- Schema templates
- Generic encoding configuration

Description

Types and functions for working with Swagger parameter schema.

Synopsis

- class ToParamSchema a where
- genericToParamSchema :: forall proxy a t. (Generic a, GToParamSchema (Rep a)) => SchemaOptions -> proxy a -> ParamSchema t
- toParamSchemaBoundedIntegral :: forall proxy a t. (Bounded a, Integral a) => proxy a -> ParamSchema t
- passwordParamSchema :: ParamSchema t
- binaryParamSchema :: ParamSchema t
- byteParamSchema :: ParamSchema t
- data SchemaOptions = SchemaOptions {
  - fieldLabelModifier :: String -> String
  - constructorTagModifier :: String -> String
  - datatypeNameModifier :: String -> String
  - allNullaryToStringTag :: Bool
  - unwrapUnaryRecords :: Bool
  }
- defaultSchemaOptions :: SchemaOptions

# Encoding

class ToParamSchema a where #

Convert a type into a plain ``ParamSchema``.

An example type and instance:

    {-# LANGUAGE OverloadedStrings #-}   -- allows to write Text literals

    import Control.Lens

    data Direction = Up | Down

    instance ToParamSchema Direction where
      toParamSchema _ = mempty
         & type_ .~ SwaggerString
         & enum_ ?~ [ "Up", "Down" ]

Instead of manually writing your ``ToParamSchema`` instance you can use a default generic implementation of ``toParamSchema``.

To do that, simply add `deriving `Generic`` clause to your datatype and declare a ``ToParamSchema`` instance for your datatype without giving definition for ``toParamSchema``.

For instance, the previous example can be simplified into this:

    {-# LANGUAGE DeriveGeneric #-}

    import GHC.Generics (Generic)

    data Direction = Up | Down deriving Generic

    instance ToParamSchema Direction

Methods

toParamSchema :: proxy a -> ParamSchema t #

Convert a type into a plain parameter schema.

    >>> encode $ toParamSchema (Proxy :: Proxy Integer)
    "{\"type\":\"integer\"}"

toParamSchema :: (Generic a, GToParamSchema (Rep a)) => proxy a -> ParamSchema t #

Convert a type into a plain parameter schema.

    >>> encode $ toParamSchema (Proxy :: Proxy Integer)
    "{\"type\":\"integer\"}"

Instances

ToParamSchema Bool # |
Methods toParamSchema :: proxy Bool -> ParamSchema t #
ToParamSchema Char # |
Methods toParamSchema :: proxy Char -> ParamSchema t #
ToParamSchema Double # |
Methods toParamSchema :: proxy Double -> ParamSchema t #
ToParamSchema Float # |
Methods toParamSchema :: proxy Float -> ParamSchema t #
ToParamSchema Int # |
Methods toParamSchema :: proxy Int -> ParamSchema t #
ToParamSchema Int8 # |
Methods toParamSchema :: proxy Int8 -> ParamSchema t #
ToParamSchema Int16 # |
Methods toParamSchema :: proxy Int16 -> ParamSchema t #
ToParamSchema Int32 # |
Methods toParamSchema :: proxy Int32 -> ParamSchema t #
ToParamSchema Int64 # |
Methods toParamSchema :: proxy Int64 -> ParamSchema t #
ToParamSchema Integer # |
Methods toParamSchema :: proxy Integer -> ParamSchema t #
ToParamSchema Word # |
Methods toParamSchema :: proxy Word -> ParamSchema t #
ToParamSchema Word8 # |
Methods toParamSchema :: proxy Word8 -> ParamSchema t #
ToParamSchema Word16 # |
Methods toParamSchema :: proxy Word16 -> ParamSchema t #
ToParamSchema Word32 # |
Methods toParamSchema :: proxy Word32 -> ParamSchema t #
ToParamSchema Word64 # |
Methods toParamSchema :: proxy Word64 -> ParamSchema t #
ToParamSchema () # |
    >>> encode $ toParamSchema (Proxy :: Proxy ())
    "{\"type\":\"string\",\"enum\":[\"_\"]}"
Methods toParamSchema :: proxy () -> ParamSchema t #
ToParamSchemaByteStringError Constraint ByteString => ToParamSchema ByteString # |
Methods toParamSchema :: proxy ByteString -> ParamSchema t #
ToParamSchemaByteStringError Constraint ByteString => ToParamSchema ByteString # |
Methods toParamSchema :: proxy ByteString -> ParamSchema t #
ToParamSchema Scientific # |
Methods toParamSchema :: proxy Scientific -> ParamSchema t #
ToParamSchema String # |
Methods toParamSchema :: proxy String -> ParamSchema t #
ToParamSchema Text # |
Methods toParamSchema :: proxy Text -> ParamSchema t #
ToParamSchema UTCTime # |
    >>> toParamSchema (Proxy :: Proxy UTCTime) ^. format
    Just "yyyy-mm-ddThh:MM:ssZ"
Methods toParamSchema :: proxy UTCTime -> ParamSchema t #
ToParamSchema Text # |
Methods toParamSchema :: proxy Text -> ParamSchema t #
ToParamSchema All # |
Methods toParamSchema :: proxy All -> ParamSchema t #
ToParamSchema Any # |
Methods toParamSchema :: proxy Any -> ParamSchema t #
ToParamSchema LocalTime # |
    >>> toParamSchema (Proxy :: Proxy LocalTime) ^. format
    Just "yyyy-mm-ddThh:MM:ss"
Methods toParamSchema :: proxy LocalTime -> ParamSchema t #
ToParamSchema ZonedTime # |
    >>> toParamSchema (Proxy :: Proxy ZonedTime) ^. format
    Just "yyyy-mm-ddThh:MM:ss+hhMM"
Methods toParamSchema :: proxy ZonedTime -> ParamSchema t #
ToParamSchema NominalDiffTime # |
Methods toParamSchema :: proxy NominalDiffTime -> ParamSchema t #
ToParamSchema Day # | Format `"date"` corresponds to `yyyy-mm-dd` format.
Methods toParamSchema :: proxy Day -> ParamSchema t #
ToParamSchema UUID # |
Methods toParamSchema :: proxy UUID -> ParamSchema t #
ToParamSchema a => ToParamSchema [a] # |
Methods toParamSchema :: proxy [a] -> ParamSchema t #
ToParamSchema a => ToParamSchema (Dual a) # |
Methods toParamSchema :: proxy (Dual a) -> ParamSchema t #
ToParamSchema a => ToParamSchema (Sum a) # |
Methods toParamSchema :: proxy (Sum a) -> ParamSchema t #
ToParamSchema a => ToParamSchema (Product a) # |
Methods toParamSchema :: proxy (Product a) -> ParamSchema t #
ToParamSchema a => ToParamSchema (First a) # |
Methods toParamSchema :: proxy (First a) -> ParamSchema t #
ToParamSchema a => ToParamSchema (Last a) # |
Methods toParamSchema :: proxy (Last a) -> ParamSchema t #
ToParamSchema a => ToParamSchema (Set a) # |
Methods toParamSchema :: proxy (Set a) -> ParamSchema t #
ToParamSchema a => ToParamSchema (Vector a) # |
Methods toParamSchema :: proxy (Vector a) -> ParamSchema t #
ToParamSchema a => ToParamSchema (Vector a) # |
Methods toParamSchema :: proxy (Vector a) -> ParamSchema t #
ToParamSchema a => ToParamSchema (Vector a) # |
Methods toParamSchema :: proxy (Vector a) -> ParamSchema t #
ToParamSchema a => ToParamSchema (Vector a) # |
Methods toParamSchema :: proxy (Vector a) -> ParamSchema t #
ToParamSchema a => ToParamSchema (HashSet a) # |
Methods toParamSchema :: proxy (HashSet a) -> ParamSchema t #

# Generic schema encoding

genericToParamSchema :: forall proxy a t. (Generic a, GToParamSchema (Rep a)) => SchemaOptions -> proxy a -> ParamSchema t #

A configurable generic ``ParamSchema`` creator.

    >>> :set -XDeriveGeneric
    >>> data Color = Red | Blue deriving Generic
    >>> encode $ genericToParamSchema defaultSchemaOptions (Proxy :: Proxy Color)
    "{\"type\":\"string\",\"enum\":[\"Red\",\"Blue\"]}"

toParamSchemaBoundedIntegral :: forall proxy a t. (Bounded a, Integral a) => proxy a -> ParamSchema t #

Default plain schema for ``Bounded``, ``Integral`` types.

    >>> encode $ toParamSchemaBoundedIntegral (Proxy :: Proxy Int8)
    "{\"maximum\":127,\"minimum\":-128,\"type\":\"integer\"}"

# Schema templates

passwordParamSchema :: ParamSchema t #

Default schema for password string. `"password"` format is used to hint UIs the input needs to be obscured.

binaryParamSchema :: ParamSchema t #

Default schema for binary data (any sequence of octets).

byteParamSchema :: ParamSchema t #

Default schema for binary data (base64 encoded).

# 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. 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
    , unwrapUnaryRecords     = False
    }