Module: OpenapiMinitest::DSL

Defined in:
lib/openapi_minitest/dsl.rb

Instance Method Summary collapse

Instance Method Details

#document_response(schema: nil, summary: nil, description: nil, tags: [], operation_id: nil, deprecated: false, strict: nil) ⇒ Object

Records the current request/response for OpenAPI documentation.

Call this after making a request and asserting the response status. It captures all the details needed for OpenAPI generation.

Examples:

Basic usage

def test_returns_users
  get "/api/users"
  assert_response 200
  document_response schema: :UserList, description: "Returns all users"
end

With tags and summary

def test_creates_user
  post "/api/users", params: { name: "John" }
  assert_response 201
  document_response schema: :User, summary: "Create user", tags: ["Users"]
end

Inline schema

def test_health_check
  get "/health"
  assert_response 200
  document_response schema: { type: :object, properties: { status: { type: :string } } }
end

Without schema (just documents the endpoint)

def test_deletes_user
  delete "/api/users/1"
  assert_response 204
  document_response description: "User deleted"
end

Strict validation (fails if response has undocumented fields)

def test_returns_user_strict
  get "/api/users/1"
  assert_response 200
  document_response schema: :User, strict: true
end

Parameters:

  • schema (Symbol, Hash, nil) (defaults to: nil) —

    Schema name (references defined schema) or inline schema hash

  • summary (String, nil) (defaults to: nil) —

    Short summary of the operation (defaults to test name)

  • description (String, nil) (defaults to: nil) —

    Description of this specific response

  • tags (Array<String>) (defaults to: []) —

    Tags for grouping endpoints

  • operation_id (String, nil) (defaults to: nil) —

    Unique operation identifier

  • deprecated (Boolean) (defaults to: false) —

    Whether this endpoint is deprecated

  • strict (Boolean, nil) (defaults to: nil) —

    Strict validation mode - fails if response contains undocumented fields. When nil (default), uses the global config.strict_validation setting.



57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
 
# File 'lib/openapi_minitest/dsl.rb', line 57

def document_response(schema: nil, summary: nil, description: nil, tags: [], operation_id: nil, deprecated: false, strict: nil)
  # Validate schema if provided and validation is enabled
  if schema && OpenapiMinitest.configuration.validate_schema && response.body.present?
    use_strict = strict.nil? ? OpenapiMinitest.configuration.strict_validation : strict
    validate_response_schema!(schema, strict: use_strict)
  end

  # Record for OpenAPI generation
  ResultCollector.instance.record(
    request: request,
    response: response,
    schema: normalize_schema(schema),
    summary: summary || generate_summary,
    description: description,
    tags: Array(tags),
    operation_id: operation_id,
    deprecated: deprecated,
    test_name: name
  )
end