Back to Repositories

Testing API Documentation Implementation in ruby-grape/grape

This test suite evaluates the documentation functionality in Grape API, focusing on parameter documentation and endpoint behavior. It verifies both documented and undocumented endpoint scenarios, ensuring proper parameter handling and documentation generation.

Test Coverage Overview

The test suite provides comprehensive coverage of Grape API’s documentation features.

Key areas tested include:

Parameter documentation with type and description
Documentation hash support for parameters
Undocumented endpoint behavior
Parameter declaration and processing

Implementation Analysis

The testing approach uses RSpec to verify Grape API’s documentation mechanisms. It employs subject-based testing patterns with class instantiation and route examination.

Framework features utilized:

RSpec context blocks for scenario separation
Before hooks for test setup
Route inspection for documentation verification
HTTP request testing for parameter processing

Technical Details

Testing infrastructure includes:

RSpec testing framework
Grape API framework
HTTP request handling
JSON response processing

Configuration involves class inheritance from Grape::API and route definition setup.

Best Practices Demonstrated

The test suite exemplifies strong testing practices through organized and focused test cases.

Notable practices include:

Isolated test contexts
Clear test case separation
Comprehensive assertion coverage
Proper setup and teardown patterns
Explicit expectation definition

ruby-grape/grape

spec/grape/api/documentation_spec.rb

            
# frozen_string_literal: true

describe Grape::API do
  subject { Class.new(described_class) }

  let(:app) { subject }

  context 'an endpoint with documentation' do
    it 'documents parameters' do
      subject.params do
        requires 'price', type: Float, desc: 'Sales price'
      end
      subject.get '/'

      expect(subject.routes.first.params['price']).to eq(required: true,
                                                         type: 'Float',
                                                         desc: 'Sales price')
    end

    it 'allows documentation with a hash' do
      documentation = { example: 'Joe' }

      subject.params do
        requires 'first_name', documentation: documentation
      end
      subject.get '/'

      expect(subject.routes.first.params['first_name'][:documentation]).to eq(documentation)
    end
  end

  context 'an endpoint without documentation' do
    before do
      subject.do_not_document!

      subject.params do
        requires :city, type: String, desc: 'Should be ignored'
        optional :postal_code, type: Integer
      end
      subject.post '/' do
        declared(params).to_json
      end
    end

    it 'does not document parameters for the endpoint' do
      expect(subject.routes.first.params).to eq({})
    end

    it 'still declares params internally' do
      data = { city: 'Berlin', postal_code: 10_115 }

      post '/', data

      expect(last_response.body).to eq(data.to_json)
    end
  end
end