module OpenAPI::Generator

Overview

An OpenAPI yaml specifications file generator.

Complete example

require "openapi-generator"

# The following example is using [Amber](https://amberframework.org/)
# but this library is compatible with any web framework.

require "amber"
require "openapi-generator/providers/amber"

# Optional: auto-serialize classes into openapi schema.
# A typed Model class can be used as the source of truth.
class Coordinates
  extend OpenAPI::Generator::Serializable

  def initialize(@lat, @long); end

  property lat : Int32
  property long : Int32
end

# Annotate the methods that will appear in the openapi file.
class Controller < Amber::Controller::Base
  include OpenAPI::Generator::Controller

  @[OpenAPI(<<-YAML
    tags:
    - tag
    summary: A brief summary of the method.
    requestBody:
      required: true
      content:
        #{Schema.ref Coordinates}
    required: true
    responses:
      200:
        description: OK
      #{Schema.error 404}
  YAML
  )]
  def method
    # Some code…
  end
end

# Add the routes.
Amber::Server.configure do
  routes :api do
    post "/method/:id", Controller, :method
  end
end

# Generate the openapi file.

OpenAPI::Generator.generate(
  provider: OpenAPI::Generator::RoutesProvider::Amber.new
)

Will produce an ./openapi.yaml file with the following contents:

---
openapi: 3.0.1
info:
  title: Server
  version: "1"
paths:
  /method/{id}:
    post:
      tags:
      - tag
      summary: A brief summary of the method.
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
        example: id
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Coordinates'
        required: true
      responses:
        "200":
          description: OK
        "404":
          description: Not Found.
    options:
      tags:
      - tag
      summary: A brief summary of the method.
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
        example: id
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Coordinates'
        required: true
      responses:
        "200":
          description: OK
        "404":
          description: Not Found.
components:
  schemas:
    Coordinates:
      required:
      - lat
      - long
      type: object
      properties:
        lat:
          type: integer
        long:
          type: integer
  responses: {}
  parameters: {}
  examples: {}
  requestBodies: {}
  headers: {}
  securitySchemes: {}
  links: {}
  callbacks: {}

Usage

Extended Modules

• OpenAPI::Generator

Defined in:

Constant Summary

DEFAULT_OPTIONS = {output: Path[Dir.current] / "openapi.yaml"}

Instance Method Summary

• #generate(provider : OpenAPI::Generator::RoutesProvider::Base, *, options = NamedTuple.new, base_doc = {info: {title: "Server", version: "1"}, components: NamedTuple.new})

  Generate an OpenAPI yaml file.

Instance Method Detail

class MockProvider < OpenAPI::Generator::RoutesProvider::Base
  def route_mappings : Array(OpenAPI::Generator::RouteMapping)
    [
      {"get", "/{id}", "HelloController::index", ["id"]},
      {"head", "/{id}", "HelloController::index", ["id"]},
      {"options", "/{id}", "HelloController::index", ["id"]},
    ]
  end
end

options = {
  output: Path[Dir.current] / "public" / "openapi.yaml",
}
base_doc = {
  info: {
    title:   "Test",
    version: "0.0.1",
  },
  components: NamedTuple.new,
}
OpenAPI::Generator.generate(
  MockProvider.new,
  options: options,
  base_doc: base_doc
)