module OpenAPI::Generator::Helpers::ActionController

Overview

Helpers that can be used inside an ActionController 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.
• param can infer query parameters.

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

require "json"
require "openapi-generator/helpers/action-controller"

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

  @[OpenAPI(
    <<-YAML
      summary: Sends a hello payload
    YAML
  )]
  def index
    # Infers query parameters.
    param mandatory : String, description: "A mandatory query parameter"
    param optional : String?, 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

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

OpenAPI::Generator::Helpers::ActionController.bootstrap
OpenAPI::Generator.generate(OpenAPI::Generator::RoutesProvider::ActionController.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:

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.

• param(declaration, description, multiple = false, schema = nil, **args)

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

• render(status_code = :ok, head = Nop, json = Nop, yaml = Nop, xml = Nop, html = Nop, text = Nop, binary = Nop, template = Nop, partial = Nop, layout = nil, description = nil, headers = nil, links = nil, type = nil, schema = nil)

  Same as the ActionController method with automatic response inference.

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

  Same as the ActionController method with automatic response inference.

• respond_without_body(code = 200, description = nil, headers = nil, links = nil)

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

Class Method Detail

Macro Detail

# 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

param name : String = "default", "A user name."