@@ -272,6 +272,28 @@ import Data.Swagger.Internal
272272-- "{\"age\":28,\"name\":\"David\"}"
273273-- >>> encode $ toSchema (Proxy :: Proxy Person)
274274-- "{\"required\":[\"name\",\"age\"],\"properties\":{\"name\":{\"type\":\"string\"},\"age\":{\"type\":\"integer\"}},\"type\":\"object\"}"
275+--
276+-- Please note that not all valid Haskell data types will have a proper swagger schema. For example while we can derive a
277+-- schema for basic enums like
278+--
279+-- >>> data SampleEnum = ChoiceOne | ChoiceTwo deriving Generic
280+-- >>> instance ToSchema SampleEnum
281+-- >>> instance ToJSON SampleEnum
282+--
283+-- and for sum types that have constructors with values
284+--
285+-- >>> data SampleSumType = ChoiceInt Int | ChoiceString String deriving Generic
286+-- >>> instance ToSchema SampleSumType
287+-- >>> instance ToJSON SampleSumType
288+--
289+-- we can not derive a valid schema for a mix of the above. The following will result in a bad schema
290+--
291+-- >>> data BadMixedType = ChoiceBool Bool | JustTag deriving Generic
292+-- >>> instance ToSchema BadMixedType
293+-- >>> instance ToJSON BadMixedType
294+--
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.
296+--
275297
276298-- $manipulation
277299-- Sometimes you have to work with an imported or generated @'Swagger'@.