Treat unknown properties as invalid + some new helpers

[fizruk]

In some cases an easy mistake in ToJSON or ToSchema instances could make them incompatible while leaving validateToJSON tests passing.

The problem is that unknown properties in a JSON object are ignored when Schema does not have an additionalProperties schema. If Schema also does not have any required properties, then validateToJSON will most certainly pass without a warning or error.

Invalid ToJSON-ToSchema Examples

Mixed sum types and genericDeclareNamedSchemaUnrestricted

Deriving ToSchema for mixed sum types is not allowed since 2.1.5 without an unrestricted version:

data Status
  = StatusOk
  | StatusError String
  deriving (Generic, ToJSON)

instance ToSchema Status where
  declareNamedSchema = genericDeclareNamedSchemaUnrestricted defaultSchemaOptions

Resulting ToJSON and ToSchema instances don't match, and, worse, validateToJSON is silent:

>>> validateToJSON StatusOk
[]

This PR makes this change:

>>> validateToJSON StatusOk
["property \"tag\" is found in JSON value, but it is not mentioned in Swagger schema"]

Newtypes for maps with bounded enum keys

When you have a Map with just a few possible values for keys, it makes sense to list them (and only them) in your Swagger Schema:

data ButtonState = Neutral | Focus | Active
  deriving (Show, Eq, Ord, Bounded, Enum, Generic)

instance ToJSON ButtonState
instance ToSchema ButtonState
instance ToJSONKey ButtonState where toJSONKey = toJSONKeyText (T.pack . show)

type ImageUrl = T.Text

newtype ButtonImages = ButtonImages { getButtonImages :: Map ButtonState ImageUrl }
  deriving (Show, Generic)

instance ToJSON ButtonImages

-- | Use a custom Schema to list all possible keys.
instance ToSchema ButtonImages where
  declareNamedSchema _ = do
    imageUrlRef <- declareSchemaRef (Proxy :: Proxy ImageUrl)
    return $ NamedSchema (Just "ButtonImages") $ mempty
      & type_ .~ SwaggerObject
      & properties.at "Neutral" ?~ imageUrlRef
      & properties.at "Focus"   ?~ imageUrlRef
      & properties.at "Active"  ?~ imageUrlRef

However, in this example ToJSON and ToSchema don't match, yet validateToJSON is silent:

>>> validateToJSON (ButtonImages mempty)
[]

This PR makes this change:

>>> validateToJSON (ButtonImages mempty)
["property \"getButtonImages\" is found in JSON value, but it is not mentioned in Swagger schema"]

Moreover, this PR introduces helper for this sort of ToSchema instances:

instance ToSchema ButtonImages where
  declareNamedSchema = genericDeclareNamedSchemaNewtype defaultSchemaOptions
    declareSchemaBoundedEnumKeyMapping

[phadej]

LGTM. Is there something which I should check more closely?

[fierce-katie]

Maybe we should move common types used for tests (like Color, Paint, ButtonImages, etc.) to a separate module?

[fizruk]

@fierce-katie yeah, later :)

@phadej no, just sanity check was needed, thanks! :)