rspec-openapi

rspec-openapi is a tool used to generate OpenAPI schemas directly from RSpec request specs.

Key advantages include:

• No special DSL required: Unlike other gems that require a custom domain-specific language, rspec-openapi works with your existing request specs without modification.
• Preserves manual changes: When merging automated changes from specs into your OpenAPI files, it attempts to keep manual modifications that cannot be fully automated from the specs.

rspec-openapi v0.7.0+ supports the $ref mechanism. You can manually replace duplicated schema structures in your doc/openapi.yaml with $ref pointers (e.g., $ref: "#/components/schemas/User"). When you re-run the generator, it will automatically detect these references and populate the #/components/schemas section with the corresponding schema definitions.

paths:
  "/users":
    get:
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/User"
components:
  schemas:
    User:
      type: object
      properties:
        id: { type: string }
        name: { type: string }

While primarily designed for RSpec, rspec-openapi provides experimental support for minitest. To use it, call the openapi! method within your test class. This works for classes inheriting from ActionDispatch::IntegrationTest or those using Rack::Test directly.

Limitations:

• Custom per-test case metadata is not currently supported.
• Custom description_builder is not currently supported.

class TablesTest < ActionDispatch::IntegrationTest
  openapi!

  test "GET /index returns a list of tables" do
    get '/tables', params: { page: '1', per: '10' }, headers: { authorization: 'k0kubun' }
    assert_response :success
  end

  test "GET /index does not return tables if unauthorized" do
    get '/tables'
    assert_response :unauthorized
  end
end

To prevent specific RSpec examples or groups from being included in the generated OpenAPI schema, set openapi: false in the RSpec metadata.

# Exclude an entire describe block
RSpec.describe '/resources', type: :request, openapi: false do
  # ...
end

# Exclude a single test case
rit 'returns a resource', openapi: false do
  # ...
end

To use rspec-openapi in your Ruby application, add it to your Gemfile within the :test group.

gem 'rspec-openapi', group: :test

To trigger the generation of the doc/openapi.yaml file when running Minitest, you must set the OPENAPI environment variable to 1 during your test run.

$ OPENAPI=1 bundle exec rails t

To generate an OpenAPI schema file from your RSpec request specs, run your RSpec suite with the OPENAPI=1 environment variable. By default, this will generate a doc/openapi.yaml file containing the paths, parameters, and responses derived from your specs.

$ OPENAPI=1 bundle exec rspec

When building schemas, you can control how examples are emitted using the example_mode on a record. This affects both request bodies and response content:

• :none: Opts out of recording examples. The description is treated as provisional and stashed under :_fallback_description until a documented test sets a permanent one.
• :single (default): Emits a single example object. It may also include metadata like _example_key and _example_summary if enabled.
• :multiple: Emits an examples object where each example is keyed by record.example_key, allowing for multiple named examples in the schema.

The library recognizes specific media types as sequential (streaming), meaning the body is treated as a sequence of items rather than a single document. For these types, the raw body is kept unparsed and split per item using the StreamParser.

Supported sequential media types:

• application/jsonl
• application/x-ndjson
• application/json-seq
• text/event-stream

The example_mode metadata option controls whether RSpec examples provide a single example or multiple examples for the request and response in the generated OpenAPI schema.

Valid modes are :single, :multiple, or :none. You can specify a single mode for both sides, or use a Hash to specify different modes for the request and response.

Deprecation Warning: Using example_mode: :multiple is currently a shorthand for { request: :single, response: :multiple }. A future major version will change this shorthand to { request: :multiple, response: :multiple }. To avoid ambiguity, it is recommended to use the explicit Hash form.

# Shorthand (Deprecated behavior: request: :single, response: :multiple)
example_mode: :multiple

# Explicit Hash (Recommended)
example_mode: { request: :single, response: :multiple }

# Both sides single
example_mode: :single

You can define additional_properties for the OpenAPI schema. The extractor supports several levels of specificity to allow fine-grained control over how extra properties are handled in the request and response:

• additional_properties: The base configuration applied to both request and response.
• request_additional_properties: Overrides the base for the request.
• response_additional_properties: Overrides the base for the response.
• hybrid_additional_properties: A base for hybrid configurations.
• request_hybrid_additional_properties: Overrides the hybrid base for the request.
• response_hybrid_additional_properties: Overrides the hybrid base for the response.