Outdated documentation re sum encoding differs ToSchema/ToJSON?

[brprice]

There is (in the haddock documentation) a statement that the default ToSchema and ToJSON instances differ in encoding sum types:

openapi3/src/Data/OpenApi.hs

Lines 330 to 333 in 8119d13

	-- @'ToSchema'@ default implementation is also aligned with @'ToJSON'@ default implementation with
	-- the only difference being for sum encoding. @'ToJSON'@ defaults sum encoding to @'defaultTaggedObject'@,
	-- while @'ToSchema'@ defaults to something which corresponds to @'ObjectWithSingleField'@. This is due to
	-- @'defaultTaggedObject'@ behavior being hard to specify in Swagger.

However, I think this is outdated and that you create a consistent schema using oneOf, as mentioned further down the documentation

openapi3/src/Data/OpenApi.hs

Lines 362 to 364 in 8119d13

	-- This package implements OpenAPI 3.0 spec, which supports @oneOf@ in schemas, allowing any sum types
	-- to be faithfully represented. All sum encodings supported by @aeson@ are supported here as well, with
	-- an exception of 'Data.Aeson.TwoElemArray', since OpenAPI spec does not support heterogeneous arrays.

Do (default) schemas for sum types agree with aeson, or am I missing something here (I cannot come up with a case where they disagree)?

[maksbotan]

Thanks for the observation! Looks like the first paragraph you mentioned survived as-is from swagger2 repo, along with some other comments in this file.

Would you like to make a PR to clean the docs?