# spec/requests/api/v1/health_spec.rb
require 'swagger_helper'

RSpec.describe 'Health API', type: :request do
  path '/api/v1/health' do
    get 'Get API health status' do
      tags 'Health'
      produces 'application/json'

      response '200', 'health status' do
        schema type: :object,
          properties: {
            status: { type: :string, enum: ['healthy'] },
            version: { type: :string },
            timestamp: { type: :string, format: 'date-time' }
          },
          required: ['status', 'version', 'timestamp']

        run_test!
      end
    end
  end
end
```

This spec does a few things:

- Defines the `/api/v1/health` endpoint as a `GET` request
- Categorizes it under the `'Health'` tag for organization
- Specifies that it produces JSON responses
- Documents the expected `200` response with a detailed schema
- Uses `run_test!` to execute the test and validate the actual response

The `run_test!` method makes a request to the API and verifies that the response matches the documented schema, helping documentation remain accurate and aligned with the implementation.

### Documenting endpoints with parameters

For more complex endpoints, such as those with parameters, request bodies, and multiple response types, more detailed specs can be created:

```ruby filename="lap_times_spec.rb"