@@ -25,8 +25,43 @@ import Data.Swagger.Internal
2525import Data.Swagger.Lens
2626import Data.Swagger.SchemaOptions
2727
28+-- | Convert a type into a plain @'ParamSchema'@.
29+--
30+-- An example type and instance:
31+--
32+-- @
33+-- {-\# LANGUAGE OverloadedStrings \#-} -- allows to write 'T.Text' literals
34+--
35+-- import Control.Lens
36+--
37+-- data Direction = Up | Down
38+--
39+-- instance ToParamSchema Direction where
40+-- toParamSchema = mempty
41+-- & schemaType .~ SwaggerString
42+-- & schemaEnum .~ [ \"Up\", \"Down\" ]
43+-- @
44+--
45+-- Instead of manually writing your @'ToParamSchema'@ instance you can
46+-- use a default generic implementation of @'toParamSchema'@.
47+--
48+-- To do that, simply add @deriving 'Generic'@ clause to your datatype
49+-- and declare a @'ToParamSchema'@ instance for your datatype without
50+-- giving definition for @'toParamSchema'@.
51+--
52+-- For instance, the previous example can be simplified into this:
53+--
54+-- @
55+-- {-\# LANGUAGE DeriveGeneric \#-}
56+--
57+-- import GHC.Generics (Generic)
58+--
59+-- data Direction = Up | Down deriving Generic
60+--
61+-- instance ToParamSchema Direction
62+-- @
2863class ToParamSchema a where
29− -- | Convert a type into a non-body parameter schema.
64+ -- | Convert a type into a plain parameter schema.
3065 toParamSchema :: proxy a -> ParamSchema t i
3166 default toParamSchema :: (Generic a, GToParamSchema (Rep a)) => proxy a -> ParamSchema t i
3267 toParamSchema = genericToParamSchema defaultSchemaOptions
@@ -52,6 +87,7 @@ instance ToParamSchema Word16 where toParamSchema = toParamSchemaBoundedIntegral
5287instance ToParamSchema Word32 where toParamSchema = toParamSchemaBoundedIntegral
5388instance ToParamSchema Word64 where toParamSchema = toParamSchemaBoundedIntegral
5489
90+-- | Default plain schema for @'Bounded'@, @'Integral'@ types.
5591toParamSchemaBoundedIntegral :: forall proxy a t i. (Bounded a, Integral a) => proxy a -> ParamSchema t i
5692toParamSchemaBoundedIntegral _ = mempty
5793 & schemaType .~ SwaggerInteger
@@ -120,6 +156,7 @@ instance ToParamSchema a => ToParamSchema (First a) where toParamSchema _ = to
120156instance ToParamSchema a => ToParamSchema (Last a) where toParamSchema _ = toParamSchema (Proxy :: Proxy a)
121157instance ToParamSchema a => ToParamSchema (Dual a) where toParamSchema _ = toParamSchema (Proxy :: Proxy a)
122158
159+-- | A configurable generic @'ParamSchema'@ creator.
123160genericToParamSchema :: forall proxy a t i. (Generic a, GToParamSchema (Rep a)) => SchemaOptions -> proxy a -> ParamSchema t i
124161genericToParamSchema opts _ = gtoParamSchema opts (Proxy :: Proxy (Rep a)) mempty
125162