Schema

Optimal results

For optimal output it's recommended that you:

• decorate your route functions with return types (assumes no body if not decorated)
• decorate your models to improve JSON schema

class Comments < Application
  base "/comments"

  # description of your model that will be used in the OpenAPI output
  class Comment
    include JSON::Serializable

    # add format information to the output schema
    @[JSON::Field(format: "email")]
    property reply_to : String
    property user_id : Int64
    property text : String
  end

  # This is a route summary
  @[AC::Route::GET("/:comment_id")]
  def show(comment_id : Int64) : Comment
    Comment.find(comment_id)
  end
end

Schema descriptions

JSON schema is automatically extracted for all the types being serialised / deserialised including:

• Parameters (route and query)
• Request bodies
• Response bodies

For JSON::Serializable types you can include additional information.

class Comment
  include JSON::Serializable

  # add format information to the output schema
  @[JSON::Field(format: "email")]
  property reply_to : String
  property user_id : Int64

  @[JSON::Field(format: "email")]
  property text : String

  # The `EpochConverter` here means the JSON value will actually be an integer
  # to avoid the schema output being `type: "string", format: "date-time"` you can
  # supply a type override and custom format string.
  @[JSON::Field(converter: Time::EpochConverter, type: "integer", format: "Int64")]
  getter time : Time
end

Some of the @[JSON::Field] annotations you can use are:

• type
• format
• pattern
• min_length
• max_length
• multiple_of
• minimum
• exclusive_minimum
• maximum
• exclusive_maximum

as per the JSON Schema spec

Custom types

If your model doesn't use JSON::Serializable and instead is using a custom serializer then you can implment def self.json_schema(openapi : Bool? = nil) to return a NamedTuple with the JSON Schema representation of your model.