Literal::Openapi

Generate OpenAPI 3.0 / 3.1 schemas from classes annotated with the literal gem's type system. Converts prop declarations into JSON Schema fragments, with pluggable adapters per OpenAPI version.

Installation

Add to your Gemfile:

gem "literal_openapi"

Then run bundle install.

Usage

Include Literal::Openapi::Serializable into any class to make it OpenAPI-documentable:

class ConnectionSerializer
  include Literal::Openapi::Serializable

  prop :public_id, String, description: "The public ID."
  prop :status, String, enum: %w[ok error], description: "Status."
  prop :email, _String?, description: "Optional email."
  prop :accounts, _Array(_Ref(AccountSerializer)), description: "Accounts."
end

ConnectionSerializer.openapi_schema
# => { "type" => "object", "properties" => { ... }, ... }

Adapters

Pick an OpenAPI version via Literal::Openapi::OpenAPI[...]:

Literal::Openapi::OpenAPI["3.0"].new.build_schema(ConnectionSerializer)
Literal::Openapi::OpenAPI["3.1"].new.build_schema(ConnectionSerializer)

Rake task

In a Rails app, the gem auto-loads a rake task via Railtie:

bundle exec rake literal_openapi:schema

Generates one YAML file per ApplicationSerializer subclass under openapi/schemas/.

Development

bin/setup
bundle exec rspec
bundle exec rubocop

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/ForTheYin/literal_openapi.