Eazypi

bundle exec rake release

Installation

Install the gem and add to the application's Gemfile by executing:

$ bundle add eazypi

If bundler is not being used to manage dependencies, install the gem by executing:

$ gem install eazypi

TODO

Currently this is in pre-alpha phase, and lot is left to do.

• Use components automatically
• Enforce input
  • Fix array for query parameters
• Variants of serializers
• Enforce output
• Examples into schema
• Output headers
• Security
• Tags
• Basic conformance

Usage

Create an API definition

Create a new API class and include Eazypi::Api. Then use the DSL helper methods to define the API. Per OpenAPI spec it is required to include the info

class Api::V1::Example
  include Eazypi::Api

  info do
    title "Example API"

    version "0.0.1"
  end
end

Create a controller Class

Create a normal rails controller and use the DSL to define operations.

class Api::V1::ExampleController
  operation :get, '/examples' do
    response 200, [String]

    render do
      render json: { examples: ['A', 'B'] }
    end
  end
end

Also for every new controller you need to define it in your Api Definition from before

class Api::V1::Example
  ...

  load_controller_class Api::V1::ExampleController
end

Mount routes

In config/routes mount your API definition

Rails.application.routes.draw do
  scope '/api/v1' do
    Api::V1::Example.mount(self)
  end
end

See openapi file

Run your rails server Go to localhost:3000/api/v1/openapi.json or localhost:3000/api/v1/openapi.yaml

Goals

The goal is to create an easy to use DSL to create nice OpenAPI defined API's.

The idea is that the code & documentation live together, but also that it is not possible to accidently change the API but not update the documentation (especially regarding input & output parameters).

Limitations

Feel free to prepare pull requests if you want to improve on these limitations

• Only application/json supported (not XML)
• Only supports OpenAPI 3.0.3

Out of scope

• No UI to render the documentation. It is recommended to do this outside your rails application. For development you can use rswag-ui or similar
• Not guaranteed to deliver valid/conformant OpenAPI spec. It is recommended to run an OpenAPI validator. We might add errors or warnings for common mistakes, but creating a spec file without errors is not guaranteed.

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and the created tag, and push the .gem file to rubygems.org.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/eazypi.