ToSchema class with Generic deriving and other helpers

[fizruk]

What's in:

• ToSchema class with default Generic-based implementation;
• genericToSchema working for some base types and record data types;
• toSchemaBoundedIntegral and toSchemaBoundedEnum helpers;
• introduce Options similar to Data.Aeson.Options (I have added fieldLabelModifier, what else do we need?);
• more tests/examples;
• more ToSchema instances for common types;
• add ToSchema instances for time types;
• ToParam/ToHeader classes (see ToParamSchema class #17);
• documentation.

@dmjio would this be useful for servant-swagger?

[dmjio]

@fizruk, fantastic work, this is definitely useful for servant-swagger, in fact this should make servant-swagger trivial to port now.

I think putting the generics based derivations in swagger2 makes more sense. I'm also a fan of using GHC.Generics as opposed to another generics library, since we incur no additional dependency cost. (And I think all other generics libraries rely on GHC.Generics anyways, since it's caked into GHC IIRC)

Still wondering if ToParam and ToHeader would be better suited for servant-swagger or swagger2. I think a case could be made for both. Either way I think it would be relatively simple to add.

Overall, great work 👍

[fizruk]

Just to keep you in loop, in recent commits I have

• changed toSchema to toNamedSchema to enable $refs;
• added Generic deriving for sum types (following ObjectWithSingleField sum encoding);
• added Generic deriving for "all nullary" data types and removed "bounded enum" helpers;
• added support for unit types (e.g. ()) following aeson which encodes unit type as [];
• added a few more options to SchemaOptions:
  • constructorTagModifier;
  • datatypeNameModifier;
  • allNullaryToStringTag;
• added more example tests;
• fixed a few things;

[fizruk]

This PR has grown big and before I start to change things even further I think it is time to merge and release.

I still am a bit uncomfortable with NamedSchema and useReferences though.
The major problem I think is that when building the entire Swagger spec we can't know for sure all needed schema definitions for a spec to be complete. Here's an example:

data Color = White | Black deriving (Generic, ToSchema)
data Dog = Dog { nick :: String, color :: Color } deriving (Generic, ToSchema)
data Person = Person { name :: String, dog :: Dog } deriving (Generic, ToSchema)

type PersonAPI
  = "person" :> ReqBody Person :> Post ()

How would you know to add Dog and Color to auto-generated swagger spec?

The solution I think should be for ToSchema to generate also a list of used definitions.
But as I have already mentioned, I would like to merge and release current changes before moving forward.

@dmjio what do you think?

[dmjio]

👍