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[...]:

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

Or pass the adapter directly to .openapi_schema:

ConnectionSerializer.openapi_schema(adapter: Literal::OpenAPI["3.1"])

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.

literal_openapi