Add OpenAPI 3.0/3.1 support with backward-compatible architecture

[numbata]

Summary

This PR adds comprehensive OpenAPI 3.0 and 3.1 support to grape-swagger through a new layered architecture, while maintaining full backward compatibility with existing Swagger 2.0 functionality.

This implementation follows the approach outlined in #928 (comment):

Rather than maintaining parallel implementations... separating the process of gathering endpoint information from the process of schema generation, possibly by using intermediate structures.

Instead of duplicating the Swagger 2.0 code and modifying it for OAS3 (which creates maintenance challenges with "two separate codebases doing almost the same job"), this PR introduces:

1. Intermediate OpenAPI Model Layer - Document, Schema, Operation, Parameter, etc.
2. Single Builder - OpenAPI::Builder::Spec that populates the model from Grape routes
3. Version-specific Exporters - Swagger2, OAS30, OAS31 that serialize the model to the target format

This architecture makes it easy to maintain both versions and leverage OpenAPI 3.x schema composition benefits.

Background

This architecture was initially prototyped in grape-oas as a standalone gem to validate the approach of using intermediate structures for multi-version OpenAPI support. This PR integrates that proven pattern directly into grape-swagger.

Usage

# Swagger 2.0 (default, unchanged)
add_swagger_documentation

# OpenAPI 3.0
add_swagger_documentation(openapi_version: '3.0')

# OpenAPI 3.1
add_swagger_documentation(openapi_version: '3.1')

Key Features

OpenAPI 3.x Support

• requestBody: Body and formData parameters converted to OAS3 requestBody format
• components/schemas: Definitions moved to components with proper $ref paths
• servers: Host/basePath/schemes converted to servers array
• securitySchemes: Security definitions moved to components
• Parameter schemas: Inline types wrapped in schema objects

OAS 3.1 Specific Features

• jsonSchemaDialect configuration option
• webhooks support
• type: ["string", "null"] for nullable (instead of nullable: true)
• License identifier field (SPDX)

Nullable Handling

Both syntaxes work across all versions:

Syntax	Swagger 2.0	OAS 3.0	OAS 3.1
documentation: { nullable: true }	x-nullable	nullable: true	type: ["string", "null"]
documentation: { x: { nullable: true } }	x-nullable	nullable: true	type: ["string", "null"]

Architecture

Grape Routes
     │
     ▼
┌─────────────────────────────┐
│  Builder::Spec              │  ← Builds OpenAPI Document model
│  (lib/grape-swagger/openapi)│
└─────────────────────────────┘
     │
     ▼
┌─────────────────────────────┐
│  OpenAPI Model Layer        │  ← Intermediate structures (Document, Schema, etc.)
│  (Document, Schema, etc.)   │
└─────────────────────────────┘
     │
     ├──────────────┬──────────────┐
     ▼              ▼              ▼
┌──────────┐  ┌──────────┐  ┌──────────┐
│ Swagger2 │  │  OAS30   │  │  OAS31   │  ← Version-specific exporters
│ Exporter │  │ Exporter │  │ Exporter │
└──────────┘  └──────────┘  └──────────┘

This separation enables:

• Single source of truth for route parsing logic
• Easy version-specific handling in exporters
• Future extensibility for new OpenAPI versions or custom formats
• Potential for DrySchema integration as schema objects (future enhancement)

Backward Compatibility

• ✅ Default behavior unchanged (Swagger 2.0)
• ✅ All existing configuration options work
• ✅ Model parsers (grape-entity, representable) work unchanged
• ✅ x: { nullable: true } syntax migrates seamlessly to OAS 3.x
• ✅ Swagger 2.0 uses x-nullable extension (not nullable)
• ✅ License identifier excluded from Swagger 2.0 output

Test Plan

• All existing Swagger 2.0 tests pass
• New OAS 3.0 integration tests
• New OAS 3.1 feature tests
• Nullable handling tests for all versions
• Backward compatibility tests for x: { nullable: true }
• Security schemes, file uploads, nested entities tested

Future Enhancements

With this architecture in place, future work could include:

• DryValidation/DrySchema support for request parameters (as separate model parser gem)
• Additional OpenAPI 3.1 features (pathItemObject in webhooks, etc.)

[Copilot]

Pull request overview

This PR adds comprehensive OpenAPI 3.0 and 3.1 support to grape-swagger through a well-architected layered approach. The implementation introduces an intermediate OpenAPI model layer that serves as a bridge between Grape routes and multiple output formats (Swagger 2.0, OAS 3.0, and OAS 3.1), maintaining full backward compatibility.

Key Changes:

• New OpenAPI model layer with version-agnostic data structures (Document, Schema, Operation, Parameter, etc.)
• Builder architecture that constructs OpenAPI models directly from Grape routes
• Version-specific exporters (Swagger2, OAS30, OAS31) that serialize models to target formats
• Support for OAS 3.x features: requestBody, components/schemas, servers array, nullable handling
• OAS 3.1-specific features: jsonSchemaDialect, webhooks, type arrays for nullable, license identifier

Reviewed changes

Copilot reviewed 70 out of 70 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
spec/swagger_v2/reference_entity_spec.rb	Added required: true to entity documentation for test accuracy
spec/swagger_v2/nullable_spec.rb	New test for Swagger 2.0 x-nullable extension handling
spec/support/route_helper.rb	Added Grape 3.1+ compatibility for Route constructor
spec/openapi_v3/*.rb	Comprehensive test suite for OAS 3.0/3.1 features
lib/grape-swagger/openapi/*.rb	Core OpenAPI model classes (Document, Schema, Operation, etc.)
lib/grape-swagger/openapi/builder/*.rb	Builder architecture for constructing OpenAPI models from Grape
lib/grape-swagger/exporter/*.rb	Version-specific exporters with shared schema export logic
spec/issues/*.rb	Fixed test expectations for entity requirements
lib/grape-swagger/doc_methods/move_params.rb	Added nullable to property_keys

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.