How to run paths in specific file or run only specific path to test swagger with rswag

Question

I have a project in which many API calls are defined with rswag to generate the open API documentation. In this project, I categorized my endpoint paths in separate ruby files.

My question is, When I am adding a new path for a new endpoint to generate swagger, Do I need to run all files and paths to test whether my documentation is right or wrong or is there any way I can run a specific path(example) or file to test only my newly added API example.

Lets take following example, I copied it for rswag github and modified.

# spec/requests/blogs_spec.rb
require 'swagger_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(:blog) { { title: 'foo', content: 'bar' } }
        run_test! do
             // some logics
        end
      end

      response '422', 'invalid request' do
        let(:blog) { { title: 'foo' } }
        run_test! do
             // some logics
        end
      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(:id) { Blog.create(title: 'foo', content: 'bar').id }
        run_test! do
             // some logics
        end
      end

      response '404', 'blog not found' do
        let(:id) { 'invalid' }
        run_test! do
             // some logics
        end
      end

      response '406', 'unsupported accept header' do
        let(:'Accept') { 'application/foo' }
        run_test! do
             // some logics
        end
      end
    end
  end
end

I need to run only test Creates a blog path with some tag. Where should I add this tag in this spec file if I need that?

I found following in rswag documentation. But I don't have an idea where should I add this tag.

# Only include tests tagged "rswag"
rake rswag:specs:swaggerize ADDITIONAL_RSPEC_OPTS="--tag rswag"

I am currently running this on a docker-compose file using following command. any update to this command would be also fine.

bundle exec rake rswag:specs:swaggerize

Any help would be really appreciated.

Answer 1

You can add tags to your RSpec tests using the :tag option. In your case, you can add the rswag tag to the specific test you want to run. Here's how you can do it:

post 'Creates a blog', :rswag do
  # ...
end

In this example, the :rswag tag is added to the 'Creates a blog' test. Now, when you run the command rake rswag:specs:swaggerize ADDITIONAL_RSPEC_OPTS="--tag rswag", only the tests with the rswag tag will be run.