rswag

OpenApi 3.0 compatible!

Seeking maintainers! Got a pet-bug that needs fixing? Just let us know in your issue/pr that you'd like to step up to help.

Rswag extends rspec-rails "request specs" with a Swagger-based DSL for describing and testing API operations. You describe your API operations with a succinct, intuitive syntax, and it automatically runs the tests. Once you have green tests, run a rake task to auto-generate corresponding OpenAPI files and expose them as YAML or JSON endpoints. Rswag also provides an embedded version of the awesome swagger-ui that's powered by the exposed file. This toolchain makes it seamless to go from integration specs, which you're probably doing in some form already, to living documentation for your API consumers.

Api Rswag creates Swagger tooling for Rails API's. Generate beautiful API documentation, including a UI to explore and test operations, directly from your rspec integration tests.

And that's not all ...

Once you have an API that can describe itself in Swagger, you've opened the treasure chest of Swagger-based tools including a client generator that can be targeted to a wide range of popular platforms. See swagger-codegen for more details.

Table of Contents

• rswag
  • Getting Started
  • The rspec DSL
    • Paths, Operations and Responses
    • Null Values
    • Support for oneOf, anyOf or AllOf schemas
    • Global Metadata
      • Supporting multiple versions of API
      • Formatting the description literals:
    • Specifying/Testing API Security
  • Configuration & Customization
    • Output Location for Generated OpenAPI Files
    • Input Location for Rspec Tests
    • Referenced Parameters and Schema Definitions
    • Request examples
    • Response headers
      • Nullable or Optional Response Headers
    • Response examples
    • Enable auto generation examples from responses
      • Dry Run Option
      • Running tests without documenting
        • rswag helper methods
    • Route Prefix for OpenAPI JSON Endpoints
    • Root Location for OpenAPI Files
    • Dynamic Values for OpenAPI JSON
    • Custom Headers for OpenAPI Files
    • Enable Swagger Endpoints for swagger-ui
    • Enable Simple Basic Auth for swagger-ui
    • Route Prefix for the swagger-ui
    • Customizing the swagger-ui
    • Serve UI Assets Directly from your Web Server

Getting Started

1. Add this line to your applications Gemfile:

   gem 'rswag'
   

   or if you like to avoid loading rspec in other bundler groups load the rswag-specs component separately. Note: Adding it to the :development group is not strictly necessary, but without it, generators and rake tasks must be preceded by RAILS_ENV=test.

   # Gemfile
   gem 'rswag-api'
   gem 'rswag-ui'
   
   group :development, :test do
     gem 'rspec-rails'
     gem 'rswag-specs'
   end
   

2. Run the install generator

   rails g rswag:install
   

   Or run the install generators for each package separately if you installed Rswag as separate gems, as indicated above:

   rails g rswag:api:install
   rails g rswag:ui:install
   RAILS_ENV=test rails g rswag:specs:install
   

3. Create an integration spec to describe and test your API. There is also a generator which can help get you started rails generate rspec:swagger API::MyController

   # spec/requests/blogs_spec.rb
   require 'openapi_helper'
   
   describe 'Blogs API' do
   
     path '/blogs' do
   
       post 'Creates a blog' do
         tags 'Blogs'
         consumes 'application/json'
         parameter name: 'blog', in: :body, schema: {
           type: :object,
           properties: {
             title: { type: :string },
             content: { type: :string }
           },
           required: [ 'title', 'content' ]
         }
   
         response '201', 'blog created' do
           let(:request_params) { { 'blog' => { title: 'foo', content: 'bar' } } } }
           run_test!
         end
   
         response '422', 'invalid request' do
           let(:request_params) { { 'blog' => { title: 'foo' } } }
           run_test!
         end
       end
     end
   
     path '/blogs/{id}' do
   
       get 'Retrieves a blog' do
         tags 'Blogs', 'Another Tag'
         produces 'application/json', 'application/xml'
         parameter name: 'id', in: :path, type: :string
         request_body_example value: { some_field: 'Foo' }, name: 'basic', summary: 'Request example description'
   
         response '200', 'blog found' do
           schema type: :object,
             properties: {
               id: { type: :integer },
               title: { type: :string },
               content: { type: :string }
             },
             required: [ 'id', 'title', 'content' ]
   
           let(:request_params) { 'id' => { Blog.create(title: 'foo', content: 'bar').id } }
           run_test!
         end
   
         response '404', 'blog not found' do
           let(:request_params) { { 'id' => 'invalid' } }
           run_test!
         end
   
         response '406', 'unsupported accept header' do
           let(:request_headers) { { 'Accept' => 'application/foo' } }
           run_test!
         end
       end
     end
   end
   

By default, the above command will create spec under spec/requests folder. You can pass an option to change this default path as in rails generate rspec:swagger API::BlogsController --spec_path integration. This will create the spec file spec/integration/blogs_spec.rb

4. Generate the OpenAPI JSON file(s)

   rake rswag:specs:swaggerize
   

   This common command is also aliased as rake rswag.

   Or if you installed your gems separately:

   RAILS_ENV=test rails rswag
   

5. Spin up your app and check out the awesome, auto-generated docs at /api-docs!

The rspec DSL

Paths, Operations and Responses

If you've used Swagger before, then the syntax should be very familiar. To describe your API operations, start by specifying a path and then list the supported operations (i.e. HTTP verbs) for that path. Path parameters must be surrounded by curly braces ({}). Within an operation block (see "post" or "get" in the example above), most of the fields supported by the Swagger "Operation" object are available as methods on the example group. To list (and test) the various responses for an operation, create one or more response blocks. Again, you can reference the Swagger "Response" object for available fields.

Take special note of the run_test! method that's called within each response block. This tells rswag to create and execute a corresponding example. It builds and submits a request based on parameter descriptions and corresponding values that have been provided using the request_params rspec variable. For example, the "post" description in the example above specifies a "body" parameter called "blog". It also lists 2 different responses. For the success case (i.e. the 201 response), notice how request_params is used to set th