Data.JsonSpec.OpenApi

This module provides tools for integrating the type-level JSON Specification with the "openapi" package.

You can use toOpenApiSchema as a low-level tool to transform json-spec Specifications into openapi3 Schemas directly, irrespective of any particular business data type.

More likely you will want to use -XDerivingVia along with EncodingSchema or DecodingSchema to derive ToSchema instances for your data types.

Example, given this data type:

data User = User
  {      name :: Text
  , lastLogin :: UTCTime
  }
  deriving ToSchema via (EncodingSchema User) -- <-- ToSchema instance defined here
instance HasJsonEncodingSpec User where
  type EncodingSpec User =
    JsonObject
      '[ '("name", JsonString)
       , '("last-login", JsonDateTime)
       ]
  toJSONStructure user =
    (Field @"name" (name user),
    (Field @"last-login" (lastLogin user),
    ()))

Calling encode (toSchema (Proxy :: Proxy User)) will produce the following Schema:

{
  "additionalProperties": false,
  "properties": {
    "last-login": {
      "format": "date-time",
      "type": "string"
    },
    "name": {
      "type": "string"
    }
  },
  "required": [
    "name",
    "last-login"
  ],
  "type": "object"
}

If you needed more control over the content of the schema you might also consider doing something like this, e.g. in the case where you would like to allow additional properties:

data User = User
  {      name :: Text
  , lastLogin :: UTCTime
  }
instance HasJsonEncodingSpec User where
  type EncodingSpec User =
    JsonObject
      '[ '("name", JsonString)
       , '("last-login", JsonDateTime)
       ]
  toJSONStructure user =
    (Field @"name" (name user),
    (Field @"last-login" (lastLogin user),
    ()))
instance ToSchema User where
  declareNamedSchema _proxy =
      pure $
        NamedSchema
          Nothing
          (
            toOpenApiSchema (EncodingSpec User)
              & set
                  additionalProperties
                  (Just (AdditionalPropertiesAllowed True))
          )

Documentation

toOpenApiSchema :: forall (spec :: Specification). Internal spec => Proxy spec -> Schema

Convert a Specification into an OpenAPI Schema. The type class Internal is an internal and opaque implementation detail and not something you should have to worry about. It should already have an instance for every possible Specification that can be constructed. If it does not, then that is a bug. Please report it! :-)

newtype EncodingSchema a

Helper for defining ToSchema instances based on HasJsonEncodingSpec using deriving via.

Example:

data MyType = ...
  deriving ToSchema via (EncodingSchema MyType)
instance HasJsonEncodingSchema MyType where
  ...

Constructors

EncodingSchema

Fields

• unEncodingSchema :: a

Instances

(Typeable a, Internal (EncodingSpec a)) => ToSchema (EncodingSchema a)

Defined in Data.JsonSpec.OpenApi

Methods

declareNamedSchema :: Proxy (EncodingSchema a) -> Declare (Definitions Schema) NamedSchema

newtype DecodingSchema a

Helper for defining ToSchema instances based on HasJsonDecodingSpec using deriving via.

Example:

data MyType = ...
  deriving ToSchema via (DecodingSchema MyType)
instance HasJsonDecodingSchema MyType where
  ...

Constructors

DecodingSchema

Fields

• unDecodingSchema :: a

Instances

(Typeable a, Internal (DecodingSpec a)) => ToSchema (DecodingSchema a)

Defined in Data.JsonSpec.OpenApi

Methods

declareNamedSchema :: Proxy (DecodingSchema a) -> Declare (Definitions Schema) NamedSchema