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))
          )