@@ -281,8 +281,17 @@ import Data.Swagger.Internal
281281-- >>> BSL.putStrLn $ encode $ toSchema (Proxy :: Proxy Person)
282282-- {"required":["name","age"],"properties":{"name":{"type":"string"},"age":{"type":"integer"}},"type":"object"}
283283--
284−-- TODO mention oneOf
284+-- This package implements OpenAPI 3.0 spec, which supports @oneOf@ in schemas, allowing any sum types
285+-- to be faithfully represented. All sum encodings supported by @aeson@ are supported here as well, with
286+-- an exception of 'Data.Aeson.TwoElemArray', since OpenAPI spec does not support heterogeneous arrays.
285287--
288+-- An example with 'Data.Aeson.TaggedObject' encoding:
289+--
290+-- >>> data Error = ErrorNoUser { userId :: Int } | ErrorAccessDenied { requiredPermission :: String } deriving Generic
291+-- >>> instance ToJSON Error
292+-- >>> instance ToSchema Error
293+-- >>> BSL.putStrLn $ encode $ toSchema (Proxy :: Proxy Error)
294+-- {"oneOf":[{"required":["userId","tag"],"type":"object","properties":{"tag":{"type":"string","enum":["ErrorNoUser"]},"userId":{"maximum":9223372036854775807,"minimum":-9223372036854775808,"type":"integer"}}},{"required":["requiredPermission","tag"],"type":"object","properties":{"tag":{"type":"string","enum":["ErrorAccessDenied"]},"requiredPermission":{"type":"string"}}}],"type":"object"}
286295
287296-- $manipulation
288297-- Sometimes you have to work with an imported or generated @'Swagger'@.