@@ -114,6 +114,10 @@ class ToSchema a where
114114 default declareNamedSchema :: (Generic a, GToSchema (Rep a)) => proxy a -> Declare Definitions NamedSchema
115115 declareNamedSchema = genericDeclareNamedSchema defaultSchemaOptions
116116
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
120+
117121-- | Convert a type into an optionally named schema.
118122toNamedSchema :: ToSchema a => proxy a -> NamedSchema
119123toNamedSchema = undeclare . declareNamedSchema
@@ -126,14 +130,18 @@ schemaName = fst . toNamedSchema
126130toSchema :: ToSchema a => proxy a -> Schema
127131toSchema = snd . toNamedSchema
128132
129−declareSchema :: ToSchema a => proxy a -> Declare Definitions Schema
130−declareSchema = fmap snd . declareNamedSchema
131−
132133-- | 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.
134135toSchemaRef :: ToSchema a => proxy a -> Referenced Schema
135136toSchemaRef = undeclare . declareSchemaRef
136137
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.
141+--
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).
137145declareSchemaRef :: ToSchema a => proxy a -> Declare Definitions (Referenced Schema)
138146declareSchemaRef proxy = do
139147 case toNamedSchema proxy of
@@ -277,14 +285,10 @@ genericToNamedSchemaBoundedIntegral opts proxy
277285 = (gdatatypeSchemaName opts (Proxy :: Proxy d), toSchemaBoundedIntegral proxy)
278286
279287-- | A configurable generic @'Schema'@ creator.
280−genericToSchema :: (Generic a, GToSchema (Rep a)) => SchemaOptions -> proxy a -> Schema
281−genericToSchema opts = snd . genericToNamedSchema opts
288+genericDeclareSchema :: (Generic a, GToSchema (Rep a)) => SchemaOptions -> proxy a -> Declare Definitions Schema
289+genericDeclareSchema opts proxy = snd <$> genericDeclareNamedSchema opts proxy
282290
283291-- | A configurable generic @'NamedSchema'@ creator.
284−genericToNamedSchema :: (Generic a, GToSchema (Rep a)) => SchemaOptions -> proxy a -> NamedSchema
285−genericToNamedSchema opts = undeclare . genericDeclareNamedSchema opts
286−
287−-- | A configurable generic @'NamedSchema'@ creator with declarations.
288292-- This function applied to @'defaultSchemaOptions'@
289293-- is used as the default for @'declareNamedSchema'@
290294-- when the type is an instance of @'Generic'@.