servant-swagger-1.1.3.1: Generate Swagger specification for your servant API.

License | BSD3
Maintainer | Nickolay Kudasov <nickolay@getshoptv.com>
Stability | experimental
Safe Haskell | None
Language | Haskell2010

Servant.Swagger.Test

Description

Automatic tests for servant API against Swagger spec.

Synopsis

- validateEveryToJSON :: forall proxy api. TMap (Every '[Typeable, Show, Arbitrary, ToJSON, ToSchema]) (BodyTypes JSON api) => proxy api -> Spec
- validateEveryToJSONWithPatternChecker :: forall proxy api. TMap (Every '[Typeable, Show, Arbitrary, ToJSON, ToSchema]) (BodyTypes JSON api) => (Pattern -> Text -> Bool) -> proxy api -> Spec

# Documentation

validateEveryToJSON #

Arguments

:: TMap (Every '[Typeable, Show, Arbitrary, ToJSON, ToSchema]) (BodyTypes JSON api) |
=> proxy api | Servant API.
-> Spec |

Verify that every type used with ``JSON`` content type in a servant API has compatible ``ToJSON`` and ``ToSchema`` instances using ``validateToJSON``.

NOTE: ``validateEveryToJSON`` does not perform string pattern validation. See ``validateEveryToJSONWithPatternChecker``.

``validateEveryToJSON`` will produce one ``prop`` specification for every type in the API. Each type only gets one test, even if it occurs multiple times in the API.

    >>> data User = User { name :: String, age :: Maybe Int } deriving (Show, Generic, Typeable)
    >>> newtype UserId = UserId String deriving (Show, Generic, Typeable, ToJSON, Arbitrary)
    >>> instance ToJSON User
    >>> instance ToSchema User
    >>> instance ToSchema UserId
    >>> instance Arbitrary User where arbitrary = User <$> arbitrary <*> arbitrary
    >>> type UserAPI = (Capture "user_id" UserId :> Get '[JSON] User) :<|> (ReqBody '[JSON] User :> Post '[JSON] UserId)

    >>> hspec $ context "ToJSON matches ToSchema" $ validateEveryToJSON (Proxy :: Proxy UserAPI)

    ToJSON matches ToSchema
      User
      UserId

    Finished in ... seconds
    2 examples, 0 failures

For the test to compile all body types should have the following instances:

- ``ToJSON`` and ``ToSchema`` are used to perform the validation;
- ``Typeable`` is used to name the test for each type;
- ``Show`` is used to display value for which ``ToJSON`` does not satisfy ``ToSchema``.
- ``Arbitrary`` is used to arbitrarily generate values.

If any of the instances is missing, you'll get a descriptive type error:

    >>> data Contact = Contact { fullname :: String, phone :: Integer } deriving (Show, Generic)
    >>> instance ToJSON Contact
    >>> instance ToSchema Contact
    >>> type ContactAPI = Get '[JSON] Contact
    >>> hspec $ validateEveryToJSON (Proxy :: Proxy ContactAPI)
    ...
    ...No instance for (Arbitrary Contact)
    ...  arising from a use of ‘validateEveryToJSON’
    ...

validateEveryToJSONWithPatternChecker #

Arguments

:: TMap (Every '[Typeable, Show, Arbitrary, ToJSON, ToSchema]) (BodyTypes JSON api) |
=> (Pattern -> Text -> Bool) | ``Pattern`` checker.
-> proxy api | Servant API.
-> Spec |

Verify that every type used with ``JSON`` content type in a servant API has compatible ``ToJSON`` and ``ToSchema`` instances using ``validateToJSONWithPatternChecker``.

For validation without patterns see ``validateEveryToJSON``.