Module: GrapeOAS

Defined in:
lib/grape_oas.rb,
lib/grape_oas/version.rb,
lib/grape_oas/exporter.rb,
lib/grape_oas/constants.rb,
lib/grape_oas/range_utils.rb,
lib/grape_oas/api_model/api.rb,
lib/grape_oas/api_model/node.rb,
lib/grape_oas/api_model/path.rb,
lib/grape_oas/rake/oas_tasks.rb,
lib/grape_oas/api_model/schema.rb,
lib/grape_oas/api_model_builder.rb,
lib/grape_oas/exporter/registry.rb,
lib/grape_oas/values_normalizer.rb,
lib/grape_oas/api_model/response.rb,
lib/grape_oas/doc_key_normalizer.rb,
lib/grape_oas/introspectors/base.rb,
lib/grape_oas/schema_constraints.rb,
lib/grape_oas/api_model/operation.rb,
lib/grape_oas/api_model/parameter.rb,
lib/grape_oas/exporter/base/paths.rb,
lib/grape_oas/exporter/oas2/paths.rb,
lib/grape_oas/exporter/oas3/paths.rb,
lib/grape_oas/type_resolvers/base.rb,
lib/grape_oas/api_model/media_type.rb,
lib/grape_oas/exporter/oas2/schema.rb,
lib/grape_oas/exporter/oas2_schema.rb,
lib/grape_oas/exporter/oas3/schema.rb,
lib/grape_oas/exporter/oas3_schema.rb,
lib/grape_oas/exporter/oas30_schema.rb,
lib/grape_oas/exporter/oas31/schema.rb,
lib/grape_oas/exporter/oas31_schema.rb,
lib/grape_oas/api_model/request_body.rb,
lib/grape_oas/exporter/oas2/response.rb,
lib/grape_oas/exporter/oas3/response.rb,
lib/grape_oas/introspectors/registry.rb,
lib/grape_oas/api_model_builders/path.rb,
lib/grape_oas/documentation_extension.rb,
lib/grape_oas/exporter/base/operation.rb,
lib/grape_oas/exporter/oas2/operation.rb,
lib/grape_oas/exporter/oas2/parameter.rb,
lib/grape_oas/exporter/oas3/operation.rb,
lib/grape_oas/exporter/oas3/parameter.rb,
lib/grape_oas/type_resolvers/registry.rb,
lib/grape_oas/api_model_builders/request.rb,
lib/grape_oas/exporter/oas3/request_body.rb,
lib/grape_oas/api_model_builders/response.rb,
lib/grape_oas/api_model_builders/operation.rb,
lib/grape_oas/exporter/concerns/tag_builder.rb,
lib/grape_oas/type_resolvers/array_resolver.rb,
lib/grape_oas/introspectors/dry_introspector.rb,
lib/grape_oas/exporter/concerns/schema_indexer.rb,
lib/grape_oas/type_resolvers/dry_type_resolver.rb,
lib/grape_oas/api_model_builders/request_params.rb,
lib/grape_oas/introspectors/entity_introspector.rb,
lib/grape_oas/type_resolvers/primitive_resolver.rb,
lib/grape_oas/api_model_builders/response_parsers/base.rb,
lib/grape_oas/api_model_builders/concerns/oas_utilities.rb,
lib/grape_oas/api_model_builders/concerns/type_resolver.rb,
lib/grape_oas/introspectors/entity_introspector_support.rb,
lib/grape_oas/api_model_builders/concerns/content_type_resolver.rb,
lib/grape_oas/introspectors/dry_introspector_support/ast_walker.rb,
lib/grape_oas/introspectors/dry_introspector_support/rule_index.rb,
lib/grape_oas/api_model_builders/response_parsers/http_codes_parser.rb,
lib/grape_oas/introspectors/dry_introspector_support/type_unwrapper.rb,
lib/grape_oas/introspectors/entity_introspector_support/cycle_tracker.rb,
lib/grape_oas/introspectors/dry_introspector_support/constraint_merger.rb,
lib/grape_oas/introspectors/dry_introspector_support/contract_resolver.rb,
lib/grape_oas/introspectors/dry_introspector_support/predicate_handler.rb,
lib/grape_oas/introspectors/entity_introspector_support/nesting_merger.rb,
lib/grape_oas/api_model_builders/request_params_support/schema_enhancer.rb,
lib/grape_oas/introspectors/dry_introspector_support/argument_extractor.rb,
lib/grape_oas/introspectors/dry_introspector_support/constraint_applier.rb,
lib/grape_oas/introspectors/dry_introspector_support/inheritance_handler.rb,
lib/grape_oas/introspectors/dry_introspector_support/type_schema_builder.rb,
lib/grape_oas/api_model_builders/response_parsers/default_response_parser.rb,
lib/grape_oas/introspectors/dry_introspector_support/constraint_extractor.rb,
lib/grape_oas/introspectors/entity_introspector_support/exposure_processor.rb,
lib/grape_oas/introspectors/entity_introspector_support/property_extractor.rb,
lib/grape_oas/introspectors/entity_introspector_support/inheritance_builder.rb,
lib/grape_oas/api_model_builders/request_params_support/param_schema_builder.rb,
lib/grape_oas/introspectors/entity_introspector_support/type_schema_resolver.rb,
lib/grape_oas/api_model_builders/request_params_support/nested_params_builder.rb,
lib/grape_oas/introspectors/entity_introspector_support/discriminator_handler.rb,
lib/grape_oas/api_model_builders/request_params_support/param_location_resolver.rb,
lib/grape_oas/api_model_builders/response_parsers/documentation_responses_parser.rb

Overview

GrapeOAS generates OpenAPI specifications from Grape APIs.

Examples:

Basic usage

schema = GrapeOAS.generate(app: MyAPI)
puts JSON.pretty_generate(schema)

Generate OpenAPI 2.0 (Swagger)

schema = GrapeOAS.generate(app: MyAPI, schema_type: :oas2)

Generate OpenAPI 3.1

schema = GrapeOAS.generate(app: MyAPI, schema_type: :oas31)

Defined Under Namespace

Modules: ApiModel, ApiModelBuilders, Constants, DocKeyNormalizer, DocumentationExtension, Exporter, Introspectors, Rake, SchemaConstraints, TypeResolvers, ValuesNormalizer Classes: ApiModelBuilder, RangeUtils

Constant Summary collapse

LOG_FORMATTER =

Formatter that prepends [grape-oas] and suppresses Logger metadata. Used by the default logger and the test capture helper.

proc { |_severity, _datetime, _progname, msg| "[grape-oas] #{msg}\n" }
VERSION = 
"1.4.0"

Class Method Summary collapse

Class Method Details

.exporters ⇒ Exporter::Registry

Returns the global exporter registry.

The registry manages exporters that generate OpenAPI specifications in different versions (OAS 2.0, 3.0, 3.1). Third-party gems can register custom exporters for new output formats.

Examples:

Registering a custom exporter

GrapeOAS.exporters.register(:custom, MyCustomExporter)

Using a custom exporter

schema = GrapeOAS.generate(app: MyAPI, schema_type: :custom)

Returns:



113
114
115
116
117
118
119
120
121
122
 
# File 'lib/grape_oas.rb', line 113

def exporters
  @exporters ||= begin
    registry = Exporter::Registry.new
    # Register built-in exporters
    registry.register(Exporter::OAS2Schema, as: :oas2)
    registry.register(Exporter::OAS30Schema, as: %i[oas3 oas30])
    registry.register(Exporter::OAS31Schema, as: :oas31)
    registry
  end
end

.generate(app:, schema_type: :oas3, **options) ⇒ Hash

Generates an OpenAPI specification from a Grape API application.

Introspects the Grape API routes, parameters, entities, and contracts to produce a complete OpenAPI specification document.

Examples:

Basic generation

schema = GrapeOAS.generate(app: MyAPI)

With custom metadata

schema = GrapeOAS.generate(
  app: MyAPI,
  schema_type: :oas3,
  title: "My API",
  version: "1.1.0"
)

Filter by namespace

schema = GrapeOAS.generate(app: MyAPI, namespace: "users")
# Only includes paths like /users, /users/{id}, etc.

Parameters:

  • app (Class<Grape::API>) —

    The Grape API class to document

  • schema_type (Symbol) (defaults to: :oas3) —

    The OpenAPI version to generate

    • ‘:oas2` - OpenAPI 2.0 (Swagger)

    • ‘:oas3` - OpenAPI 3.0 (default)

    • ‘:oas31` - OpenAPI 3.1

  • options (Hash) —

    Additional options passed to the API model builder

Options Hash (**options):

  • :title (String) —

    API title for the info section

  • :version (String) —

    API version string

  • :servers (Array<String>) —

    Server URLs (OAS3 only)

  • :license (Hash) —

    License information

  • :security_definitions (Hash) —

    Security scheme definitions

  • :namespace (String) —

    Filter routes to only include paths starting with this namespace (e.g., “users” includes /users and /users/id)

Returns:

  • (Hash) —

    The OpenAPI specification as a Hash (JSON-serializable)



194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
 
# File 'lib/grape_oas.rb', line 194

def generate(app:, schema_type: :oas3, **options)
  if options[:nullable_strategy].nil? && options.key?(:nullable_keyword) && %i[oas3 oas30].include?(schema_type)
    options[:nullable_strategy] = if options[:nullable_keyword] == false
                                    Constants::NullableStrategy::TYPE_ARRAY
                                  else
                                    Constants::NullableStrategy::KEYWORD
                                  end
  end

  api_model = GrapeOAS::ApiModelBuilder.new(options)
  api_model.add_app(app)

  GrapeOAS::Exporter.for(schema_type)
                    .new(api_model: api_model.api)
                    .generate
end

.introspectors ⇒ Introspectors::Registry

Returns the global introspector registry.

The registry manages introspectors that build schemas from various sources (e.g., Grape::Entity, Dry contracts). Third-party gems can register custom introspectors to support new schema definition formats.

Examples:

Registering a custom introspector

GrapeOAS.introspectors.register(MyCustomIntrospector)

Inserting before an existing introspector

GrapeOAS.introspectors.register(
  HighPriorityIntrospector,
  before: GrapeOAS::Introspectors::EntityIntrospector
)

Returns:



88
89
90
91
92
93
94
95
96
 
# File 'lib/grape_oas.rb', line 88

def introspectors
  @introspectors ||= begin
    registry = Introspectors::Registry.new
    # Register built-in introspectors in order of precedence
    registry.register(Introspectors::EntityIntrospector)
    registry.register(Introspectors::DryIntrospector)
    registry
  end
end

.logger ⇒ #warn

Configurable logger for schema generation warnings. Defaults to Logger on $stderr. Set to Rails.logger or Logger.new(File::NULL).

Returns:

  • (#warn) 


53
54
55
56
57
58
59
 
# File 'lib/grape_oas.rb', line 53

def logger
  @logger ||= begin
    l = Logger.new($stderr, progname: "grape-oas", level: Logger::WARN)
    l.formatter = LOG_FORMATTER
    l
  end
end

.logger=(value) ⇒ Object

Parameters:

  • value (#warn, nil) —

    a logger-compatible object, or nil to reset to the default $stderr logger

Raises:

  • (ArgumentError) 


63
64
65
66
67
 
# File 'lib/grape_oas.rb', line 63

def logger=(value)
  raise ArgumentError, "logger must respond to :warn (got #{value.class})" if value && !value.respond_to?(:warn)

  @logger = value
end

.type_resolvers ⇒ TypeResolvers::Registry

Returns the global type resolver registry.

The registry manages type resolvers that convert Grape’s stringified types back to OpenAPI schemas. Grape stores parameter types as strings for memory optimization, but TypeResolvers can resolve them back to actual classes and extract rich metadata (e.g., Dry::Types format, constraints).

Examples:

Registering a custom type resolver

GrapeOAS.type_resolvers.register(MyCustomTypeResolver)

Inserting before an existing resolver

GrapeOAS.type_resolvers.register(
  HighPriorityResolver,
  before: GrapeOAS::TypeResolvers::ArrayResolver
)

Returns:



143
144
145
146
147
148
149
150
151
152
153
154
155
 
# File 'lib/grape_oas.rb', line 143

def type_resolvers
  @type_resolvers ||= begin
    registry = TypeResolvers::Registry.new
    # Register built-in resolvers in order of precedence
    # ArrayResolver handles "[Type]" patterns first
    registry.register(TypeResolvers::ArrayResolver)
    # DryTypeResolver handles Dry::Types (standalone, not arrays)
    registry.register(TypeResolvers::DryTypeResolver)
    # PrimitiveResolver is the fallback for basic types
    registry.register(TypeResolvers::PrimitiveResolver)
    registry
  end
end

.version ⇒ String

Returns the version of the GrapeOAS gem.

Returns:

  • (String) —

    the semantic version string



40
41
42
 
# File 'lib/grape_oas.rb', line 40

def version
  OAS::VERSION
end