module OpenAPI::Generator::Helpers::Amber

Overview

Helpers that can be used inside an Amber Controller to enable inference and ensure that the code matches the contract defined in the generated OpenAPI document.

Include this module inside a Controller class to add various macros that you can use to make the generator infer some properties of the OpenAPI declaration.

body_as can infer request body types and schemas.
respond_with can infer responses types and schemas.
query_params can infer query parameters.

NOTE Do not forget to call .bootstrap once before calling OpenAPI::Generator.generate.

require "json"
require "openapi-generator/helpers/amber"

class HelloPayloadController < Amber::Controller::Base
  include ::OpenAPI::Generator::Controller
  include ::OpenAPI::Generator::Helpers::Amber

  @[OpenAPI(
    <<-YAML
      summary: Sends a hello payload
    YAML
  )]
  def index
    # Infers query parameters.
    query_params "mandatory", description: "A mandatory query parameter"
    query_params? "optional", description: "An optional query parameter"

    # Infers request body.
    body_as Payload?, description: "The request payload."

    # Infers responses.
    respond_with 200, description: "A hello payload." do
      json Payload.new, type: Payload
      xml "<hello></hello>", type: String
    end
    respond_with 201, description: "A good morning message." do
      text "Good morning.", type: String
    end
    respond_with 400 do
      text "Ouch.", type: String
    end
  end
end

class Payload
  include JSON::Serializable
  extend OpenAPI::Generator::Serializable

  def initialize(@hello : String = "world")
  end
end

Amber::Server.configure do
  routes :api do
    route "get", "/hello", HelloPayloadController, :index
  end
end

OpenAPI::Generator::Helpers::Amber.bootstrap
OpenAPI::Generator.generate(OpenAPI::Generator::RoutesProvider::Amber.new)

Will produce:

---
openapi: 3.0.1
info:
  title: Test
  version: 0.0.1
paths:
  /hello:
    get:
      summary: Sends a hello payload
      parameters:
      - name: mandatory
        in: query
        description: A mandatory query parameter
        required: true
        schema:
          type: string
      - name: optional
        in: query
        description: An optional query parameter
        required: false
        schema:
          type: string
      requestBody:
        description: The request payload.
        content:
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/Payload'
        required: false
      responses:
        "200":
          description: A hello payload?
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/Payload'
            application/xml:
              schema:
                type: string
        "201":
          description: A good morning message.
          content:
            text/plain:
              schema:
                type: string
        "400":
          description: Bad Request
          content:
            text/plain:
              schema:
                type: string
components:
  schemas:
    Payload:
      required:
      - hello
      type: object
      properties:
        hello:
          type: string
  responses: {}
  parameters: {}
  examples: {}
  requestBodies: {}
  headers: {}
  securitySchemes: {}
  links: {}
  callbacks: {}

Defined in:

openapi-generator/helpers/amber.cr

Class Method Summary

.bootstrap
Run this method exactly once before generating the schema to register all the inferred properties.

Macro Summary

body_as(type, description = nil, content_type = "application/json", constructor = :from_json)
Extracts and serialize the body from the request and registers it in the OpenAPI operation.
query_params(name, description, multiple = false, schema = nil, **args)
Fetch a query parameter and register it in the OpenAPI operation related to the controller method.
query_params?(name, description, multiple = false, schema = nil, **args)
Fetch an optional query parameter and register it in the OpenAPI operation related to the controller method.
respond_with(code = 200, description = nil, headers = nil, links = nil, &)
Same as the Amber method with automatic response inference.
respond_without_body(code = 200, description = nil, headers = nil, links = nil)
Same as the Amber method but without specifying any content and with automatic response inference.

Class Method Detail

def self.bootstrap #

Run this method exactly once before generating the schema to register all the inferred properties.

Macro Detail

macro body_as(type, description = nil, content_type = "application/json", constructor = :from_json) #

Extracts and serialize the body from the request and registers it in the OpenAPI operation.

# This will try to case the body as a SomeClass using the SomeClass.new method and assuming that the payload is a json.
body_as SomeClass, description: "Some payload.", content_type: "application/json", constructor: new
# The content_type, constructor and description can be omitted.
body_as SomeClass

macro query_params(name, description, multiple = false, schema = nil, **args) #

Fetch a query parameter and register it in the OpenAPI operation related to the controller method.

query_params "name", "A user name."

macro query_params?(name, description, multiple = false, schema = nil, **args) #

Fetch an optional query parameter and register it in the OpenAPI operation related to the controller method.

query_params? "name[]", "One or multiple user names. (optional)", multiple = true

macro respond_with(code = 200, description = nil, headers = nil, links = nil, &) #

Same as the Amber method with automatic response inference.

macro respond_without_body(code = 200, description = nil, headers = nil, links = nil) #

Same as the Amber method but without specifying any content and with automatic response inference.