@@ -286,13 +286,30 @@ import Data.Swagger.Internal
286286-- >>> instance ToSchema SampleSumType
287287-- >>> instance ToJSON SampleSumType
288288--
289−-- we can not derive a valid schema for a mix of the above. The following will result in a bad schema
290−--
289+-- we can not derive a valid schema for a mix of the above. The following will result in a type error
290+--
291291-- >>> data BadMixedType = ChoiceBool Bool | JustTag deriving Generic
292292-- >>> instance ToSchema BadMixedType
293−-- >>> instance ToJSON BadMixedType
293+-- ...
294+-- ... error:
295+-- ... • Cannot derive Generic-based Swagger Schema for BadMixedType
296+-- ... BadMixedType is a mixed sum type (has both unit and non-unit constructors).
297+-- ... Swagger does not have a good representation for these types.
298+-- ... Use genericDeclareNamedSchemaUnrestricted if you want to derive schema
299+-- ... that matches aeson's Generic-based toJSON,
300+-- ... but that's not supported by some Swagger tools.
301+-- ... • In the expression:
302+-- ... Data.Swagger.Internal.Schema.$dmdeclareNamedSchema @BadMixedType
303+-- ... In an equation for ‘declareNamedSchema’:
304+-- ... declareNamedSchema
305+-- ... = Data.Swagger.Internal.Schema.$dmdeclareNamedSchema @BadMixedType
306+-- ... In the instance declaration for ‘ToSchema BadMixedType’
307+--
308+-- We can use 'genericDeclareNamedSchemaUnrestricted' to try our best to represent this type as a Swagger Schema and match 'ToJSON':
294309--
295−-- This is due to the fact that @'ToJSON'@ encodes empty constructors with an empty list which can not be described in a swagger schema.
310+-- >>> data BadMixedType = ChoiceBool Bool | JustTag deriving Generic
311+-- >>> instance ToSchema BadMixedType where declareNamedSchema = genericDeclareNamedSchemaUnrestricted defaultSchemaOptions
312+-- >>> instance ToJSON BadMixedType
296313--
297314
298315-- $manipulation