@@ -114,6 +114,10 @@ class ToSchema a where
114 default declareNamedSchema :: (Generic a, GToSchema (Rep a)) => proxy a -> Declare Definitions NamedSchema
114 default declareNamedSchema :: (Generic a, GToSchema (Rep a)) => proxy a -> Declare Definitions NamedSchema
115 declareNamedSchema = genericDeclareNamedSchema defaultSchemaOptions
115 declareNamedSchema = genericDeclareNamedSchema defaultSchemaOptions
117+-- | Convert a type into a schema and declare all used schema definitions.
118+declareSchema :: ToSchema a => proxy a -> Declare Definitions Schema
119+declareSchema = fmap snd . declareNamedSchema
117-- | Convert a type into an optionally named schema.
121-- | Convert a type into an optionally named schema.
118toNamedSchema :: ToSchema a => proxy a -> NamedSchema
122toNamedSchema :: ToSchema a => proxy a -> NamedSchema
119toNamedSchema = undeclare . declareNamedSchema
123toNamedSchema = undeclare . declareNamedSchema
@@ -126,14 +130,18 @@ schemaName = fst . toNamedSchema
126toSchema :: ToSchema a => proxy a -> Schema
130toSchema :: ToSchema a => proxy a -> Schema
127toSchema = snd . toNamedSchema
131toSchema = snd . toNamedSchema
129−declareSchema :: ToSchema a => proxy a -> Declare Definitions Schema
130−declareSchema = fmap snd . declareNamedSchema
132-- | Convert a type into a referenced schema if possible.
133-- | Convert a type into a referenced schema if possible.
133−-- Only named schemas can be references, nameless schemas are inlined.
134+-- Only named schemas can be referenced, nameless schemas are inlined.
134toSchemaRef :: ToSchema a => proxy a -> Referenced Schema
135toSchemaRef :: ToSchema a => proxy a -> Referenced Schema
135toSchemaRef = undeclare . declareSchemaRef
136toSchemaRef = undeclare . declareSchemaRef
138+-- | Convert a type into a referenced schema if possible
139+-- and declare all used schema definitions.
140+-- Only named schemas can be referenced, nameless schemas are inlined.
142+-- Schema definitions are typically declared for every referenced schema.
143+-- If @'declareSchemaRef'@ returns a reference, a corresponding schema
144+-- will be declared (regardless of whether it is recusive or not).
137declareSchemaRef :: ToSchema a => proxy a -> Declare Definitions (Referenced Schema)
145declareSchemaRef :: ToSchema a => proxy a -> Declare Definitions (Referenced Schema)
138declareSchemaRef proxy = do
146declareSchemaRef proxy = do
139 case toNamedSchema proxy of
147 case toNamedSchema proxy of
@@ -277,14 +285,10 @@ genericToNamedSchemaBoundedIntegral opts proxy
277 = (gdatatypeSchemaName opts (Proxy :: Proxy d), toSchemaBoundedIntegral proxy)
285 = (gdatatypeSchemaName opts (Proxy :: Proxy d), toSchemaBoundedIntegral proxy)
279-- | A configurable generic @'Schema'@ creator.
287-- | A configurable generic @'Schema'@ creator.
280−genericToSchema :: (Generic a, GToSchema (Rep a)) => SchemaOptions -> proxy a -> Schema
288+genericDeclareSchema :: (Generic a, GToSchema (Rep a)) => SchemaOptions -> proxy a -> Declare Definitions Schema
281−genericToSchema opts = snd . genericToNamedSchema opts
289+genericDeclareSchema opts proxy = snd <$> genericDeclareNamedSchema opts proxy
283-- | A configurable generic @'NamedSchema'@ creator.
291-- | A configurable generic @'NamedSchema'@ creator.
284−genericToNamedSchema :: (Generic a, GToSchema (Rep a)) => SchemaOptions -> proxy a -> NamedSchema
285−genericToNamedSchema opts = undeclare . genericDeclareNamedSchema opts
287−-- | A configurable generic @'NamedSchema'@ creator with declarations.
288-- This function applied to @'defaultSchemaOptions'@
292-- This function applied to @'defaultSchemaOptions'@
289-- is used as the default for @'declareNamedSchema'@
293-- is used as the default for @'declareNamedSchema'@
290-- when the type is an instance of @'Generic'@.
294-- when the type is an instance of @'Generic'@.