@@ -272,6 +272,28 @@ import Data.Swagger.Internal
272-- "{\"age\":28,\"name\":\"David\"}"
272-- "{\"age\":28,\"name\":\"David\"}"
273-- >>> encode $ toSchema (Proxy :: Proxy Person)
273-- >>> encode $ toSchema (Proxy :: Proxy Person)
274-- "{\"required\":[\"name\",\"age\"],\"properties\":{\"name\":{\"type\":\"string\"},\"age\":{\"type\":\"integer\"}},\"type\":\"object\"}"
274-- "{\"required\":[\"name\",\"age\"],\"properties\":{\"name\":{\"type\":\"string\"},\"age\":{\"type\":\"integer\"}},\"type\":\"object\"}"
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
279+-- >>> data SampleEnum = ChoiceOne | ChoiceTwo deriving Generic
280+-- >>> instance ToSchema SampleEnum
281+-- >>> instance ToJSON SampleEnum
283+-- and for sum types that have constructors with values
285+-- >>> data SampleSumType = ChoiceInt Int | ChoiceString String deriving Generic
286+-- >>> instance ToSchema SampleSumType
287+-- >>> instance ToJSON SampleSumType
289+-- we can not derive a valid schema for a mix of the above. The following will result in a bad schema
291+-- >>> data BadMixedType = ChoiceBool Bool | JustTag deriving Generic
292+-- >>> instance ToSchema BadMixedType
293+-- >>> instance ToJSON BadMixedType
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.
276-- $manipulation
298-- $manipulation
277-- Sometimes you have to work with an imported or generated @'Swagger'@.
299-- Sometimes you have to work with an imported or generated @'Swagger'@.