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
Defined in:
openapi-generator/controller.cropenapi-generator/generator.cr
Constant Summary
-
DEFAULT_OPTIONS =
{output: Path[Dir.current] / "openapi.yaml"}
-
Log =
::Log.for(self)
Instance Method Summary
-
#generate(provider : OpenAPI::Generator::RoutesProvider::Base, *, options = NamedTuple.new, base_document = {info: {title: "Server", version: "1"}})
Generate an OpenAPI yaml file.
Instance Method Detail
def generate(provider : OpenAPI::Generator::RoutesProvider::Base, *, options = NamedTuple.new, base_document = {info: {title: "Server", version: "1"}})
#
Generate an OpenAPI yaml file.
An OpenAPI::Generator::RoutesProvider::Base
implementation must be provided.
Currently, only the Amber and Lucky providers are included out of the box but writing a custom provider should be easy.
Example
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_document = {
info: {
title: "Test",
version: "0.0.1",
},
components: NamedTuple.new,
}
OpenAPI::Generator.generate(
MockProvider.new,
options: options,
base_document: base_document
)