Setting Up Swagger in Rails Without RSpec Using Rswag

Swagger provides an interactive API documentation interface that makes it easier to explore and test API endpoints. Normally, Rswag generates Swagger documentation from RSpec tests, but if you prefer not to write specs, you can manually create and configure the documentation. This guide walks you through installing Rswag and setting up Swagger UI without writing specs.

1. Install Rswag Gems

First, add the necessary gems to your `Gemfile`:

gem 'rswag-api'
gem 'rswag-ui'
gem 'rswag-specs' # Not required if not using RSpec

Then, install the gems by running:

bundle install

After installation, run the Rswag installer to set up necessary files:

rails g rswag:install

2. Enable Swagger UI in Routes

To enable the Swagger UI, add the following to `config/routes.rb`:

mount Rswag::Ui::Engine => '/api-docs'
mount Rswag::Api::Engine => '/api-docs'

Restart your Rails server: rails s

Now, you can access the Swagger UI at: http://localhost:3000/api-docs

3. Manually Create `swagger.yaml`

Since we are not generating documentation from specs, we need to create a Swagger YAML file manually.

Create the Swagger File

mkdir -p swagger/v1
touch swagger/v1/swagger.yaml

Now, edit `swagger/v1/swagger.yaml` and add your API definitions:

swagger: "2.0"
info:
  title: "My API"
  description: "API documentation for my Rails app"
  version: "1.0"
paths:
  /contracts:
    get:
      summary: "Get all contracts"
      tags:
        - Contracts
      responses:
        "200":
          description: "Returns a list of contracts"
          schema:
            type: "array"
            items:
              type: "object"
              properties:
                id:
                  type: "integer"
                name:
                  type: "string"

4. Configure Rswag to Use Static Files

By default, Rswag looks for dynamically generated files from tests. To serve a static file, follow these steps:

1. Edit `config/initializers/rswag-ui.rb`

Create this file if it does not exist, then add:

Rswag::Ui.configure do |config|
  config.swagger_endpoint '/swagger/v1/swagger.yaml', 'API v1 Docs'
end

2. Move `swagger.yaml` to `public/`

mv swagger/v1/swagger.yaml public/swagger.yaml

3. Update the Initializer to Use the New Location

Modify `config/initializers/rswag-ui.rb`:

Rswag::Ui.configure do |config|
  config.swagger_endpoint '/swagger.yaml', 'API v1 Docs'
end

5. Restart Rails Server

Run: rails s

Now, visit:

📌 http://localhost:3000/api-docs

You should see your API documentation without writing RSpec tests!

Conclusion

You’ve successfully set up Swagger API documentation in Rails using Rswag without writing specs! 🎉

- Pros: No need to write specs, manually control API documentation.

- Cons: Must update the `swagger.yaml` file manually when API changes.

If you need further customization, consider integrating Swagger JSON generation for dynamic documentation. Let me know if you have any questions! 🚀