Add OpenAPI 3.0/3.1 support with backward-compatible architecture

README.md

@@ -18,6 +18,9 @@
     - [insert_after](#insert_after)
   - [CORS](#cors)
 - [Configure ](#configure-)
+    - [openapi_version: ](#openapi_version-)
+    - [json_schema_dialect: (OAS 3.1 only)](#json_schema_dialect-)
+    - [webhooks: (OAS 3.1 only)](#webhooks-)
     - [host: ](#host-)
     - [base_path: ](#base_path-)
     - [mount_path: ](#mount_path-)
@@ -130,7 +133,9 @@ The following versions of grape, grape-entity and grape-swagger can currently be
 
 ## Swagger-Spec <a name="swagger-spec"></a>
 
-Grape-swagger generates documentation per [Swagger / OpenAPI Spec 2.0](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md).
+Grape-swagger generates documentation per [Swagger / OpenAPI Spec 2.0](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md) by default.
+
+It also supports [OpenAPI 3.0](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.3.md) and [OpenAPI 3.1](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md). See the [openapi_version configuration option](#openapi_version) for details.
 
 <!-- validating it with: http://bigstickcarpet.com/swagger-parser/www/index.html -->
 
@@ -260,6 +265,9 @@ end
 
 ## Configure <a name="configure"></a>
 
+* [openapi_version](#openapi_version)
+* [json_schema_dialect (OAS 3.1 only)](#json_schema_dialect)
+* [webhooks (OAS 3.1 only)](#webhooks)
 * [host](#host)
 * [base_path](#base_path)
 * [mount_path](#mount_path)
@@ -294,6 +302,114 @@ add_swagger_documentation \
 ```
 
 
+#### openapi_version: <a name="openapi_version"></a>
+Specifies which OpenAPI/Swagger version to generate. By default (`nil`), Swagger 2.0 is generated.
+
+Available options:
+- `nil` - Swagger 2.0 (default, for backward compatibility)
+- `'3.0'` - OpenAPI 3.0.3
+- `'3.1'` - OpenAPI 3.1.0
+
+```ruby
+# Swagger 2.0 (default)
+add_swagger_documentation
+
+# OpenAPI 3.0
+add_swagger_documentation \
+   openapi_version: '3.0'
+
+# OpenAPI 3.1
+add_swagger_documentation \
+   openapi_version: '3.1'
+```
+
+Key differences when using OpenAPI 3.x:
+- Body parameters are converted to `requestBody` with content type wrappers
+- Schema references use `#/components/schemas/` instead of `#/definitions/`
+- Parameters include a `schema` wrapper
+- `host`, `basePath`, and `schemes` are converted to a `servers` array
+- OpenAPI 3.1 uses `type: ["string", "null"]` instead of `nullable: true`
+
+
+#### json_schema_dialect: <a name="json_schema_dialect"></a>
+**OpenAPI 3.1 only.** Specifies the JSON Schema dialect used in the document. This option is ignored for OpenAPI 3.0 and Swagger 2.0.
+
+```ruby
+add_swagger_documentation \
+   openapi_version: '3.1',
+   json_schema_dialect: 'https://json-schema.org/draft/2020-12/schema'
+```
+
+This adds `jsonSchemaDialect` to the OpenAPI 3.1 output:
+```json
+{
+  "openapi": "3.1.0",
+  "jsonSchemaDialect": "https://json-schema.org/draft/2020-12/schema",
+  ...
+}
+```
+
+
+#### webhooks: <a name="webhooks"></a>
+**OpenAPI 3.1 only.** Defines webhook endpoints that your API can call. This option is ignored for OpenAPI 3.0 and Swagger 2.0.
+
+```ruby
+add_swagger_documentation \
+   openapi_version: '3.1',
+   webhooks: {
+     newPetAvailable: {
+       post: {
+         summary: 'New pet available',
+         description: 'A new pet has been added to the store',
+         operationId: 'newPetWebhook',
+         tags: ['pets'],
+         requestBody: {
+           required: true,
+           content: {
+             'application/json': {
+               schema: {
+                 type: 'object',
+                 properties: {
+                   petId: { type: 'integer', description: 'Pet ID' },
+                   petName: { type: 'string', description: 'Pet name' }
+                 },
+                 required: %w[petId petName]
+               }
+             }
+           }
+         },
+         responses: {
+           '200': { description: 'Webhook received successfully' },
+           '400': { description: 'Invalid payload' }
+         }
+       }
+     }
+   }
+```
+
+You can also reference existing schemas:
+```ruby
+webhooks: {
+  petCreated: {
+    post: {
+      summary: 'Pet created',
+      requestBody: {
+        required: true,
+        content: {
+          'application/json': {
+            schema: { '$ref': '#/components/schemas/Pet' }
+          }
+        }
+      },
+      responses: {
+        '200': { description: 'OK' }
+      }
+    }
+  }
+}
+```
+
+
 #### host: <a name="host"></a>
 Sets explicit the `host`, default would be taken from `request`.
 ```ruby

docs/openapi_3.md

@@ -0,0 +1,113 @@
+# OpenAPI 3.0/3.1 Support
+
+## Quick Start
+
+```ruby
+# 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')
+```
+
+## Configuration Options
+
+```ruby
+add_swagger_documentation(
+  openapi_version: '3.1',
+  info: {
+    title: 'My API',
+    version: '1.0',
+    description: 'API description',
+    license: {
+      name: 'MIT',
+      url: 'https://opensource.org/licenses/MIT',
+      identifier: 'MIT'  # OAS 3.1 only (SPDX)
+    }
+  },
+  security_definitions: {
+    bearer: { type: 'http', scheme: 'bearer' }
+  },
+  # OAS 3.1 specific
+  json_schema_dialect: 'https://json-schema.org/draft/2020-12/schema',
+  webhooks: {
+    newUser: {
+      post: {
+        summary: 'New user webhook',
+        requestBody: { ... },
+        responses: { '200' => { description: 'OK' } }
+      }
+    }
+  }
+)
+```
+
+## Key Differences from Swagger 2.0
+
+| Aspect | Swagger 2.0 | OpenAPI 3.x |
+|--------|-------------|-------------|
+| Version | `swagger: '2.0'` | `openapi: '3.0.3'` / `'3.1.0'` |
+| Body params | `in: body` parameter | `requestBody` object |
+| Form params | `in: formData` | `requestBody` with content-type |
+| File upload | `type: file` | `type: string, format: binary` |
+| Schema refs | `#/definitions/X` | `#/components/schemas/X` |
+| Host | `host`, `basePath`, `schemes` | `servers: [{url: "..."}]` |
+| Security defs | `securityDefinitions` | `components/securitySchemes` |
+| Param types | inline `type`, `format` | wrapped in `schema` |
+
+## Nullable Fields
+
+```ruby
+# Recommended syntax
+params do
+  optional :nickname, type: String, documentation: { nullable: true }
+end
+
+# Also supported (for backward compatibility with Swagger 2.0 code)
+params do
+  optional :nickname, type: String, documentation: { x: { nullable: true } }
+end
+```
+
+Both syntaxes produce version-appropriate output:
+
+| Syntax | Swagger 2.0 | OAS 3.0 | OAS 3.1 |
+|--------|-------------|---------|---------|
+| `documentation: { nullable: true }` | `x-nullable: true` | `nullable: true` | `type: ["string", "null"]` |
+| `documentation: { x: { nullable: true } }` | `x-nullable: true` | `nullable: true` | `type: ["string", "null"]` |
+
+This means existing Swagger 2.0 code using `x: { nullable: true }` works seamlessly when switching to OAS 3.x.
+
+## Architecture
+
+```
+Grape Routes
+     │
+     ▼
+┌─────────────────────────────┐
+│  Builder::Spec              │
+│  (lib/grape-swagger/openapi)│
+└─────────────────────────────┘
+     │
+     ▼
+┌─────────────────────────────┐
+│  OpenAPI Model Layer        │
+│  (Document, Schema, etc.)   │
+└─────────────────────────────┘
+     │
+     ├──────────────┬──────────────┐
+     ▼              ▼              ▼
+┌──────────┐  ┌──────────┐  ┌──────────┐
+│ Swagger2 │  │  OAS30   │  │  OAS31   │
+│ Exporter │  │ Exporter │  │ Exporter │
+└──────────┘  └──────────┘  └──────────┘
+```
+
+## Backward Compatibility
+
+- **Default unchanged**: Without `openapi_version`, Swagger 2.0 is generated
+- **All existing options work**: Same configuration for both versions
+- **Model parsers unchanged**: grape-entity, representable, etc. work as before

lib/grape-swagger.rb

@@ -13,15 +13,41 @@
 require 'grape-swagger/request_param_parser_registry'
 require 'grape-swagger/token_owner_resolver'
 
+# OpenAPI 3.x support
+require 'grape-swagger/openapi'
+require 'grape-swagger/openapi/builder'
+require 'grape-swagger/exporter'
+
 module GrapeSwagger
   class << self
+    attr_writer :schema_name_generator
+
     def model_parsers
       @model_parsers ||= GrapeSwagger::ModelParsers.new
     end
 
     def request_param_parsers
       @request_param_parsers ||= GrapeSwagger::RequestParamParserRegistry.new
     end
+
+    def schema_name_generator
+      @schema_name_generator ||= default_schema_name_generator
+    end
+
+    private
+
+    def default_schema_name_generator
+      lambda { |model|
+        model_string = model.to_s
+        if model_string.end_with?('::Entity', '::Entities')
+          model_string.split('::')[0..-2].join('_')
+        elsif model_string.start_with?('Entity::', 'Entities::', 'Representable::')
+          model_string.split('::')[1..-1].join('_')
+        else
+          model_string.split('::').join('_')
+        end
+      }
+    end
   end
   autoload :Rake, 'grape-swagger/rake/oapi_tasks'
 

lib/grape-swagger/doc_methods.rb

@@ -13,6 +13,8 @@
 require 'grape-swagger/doc_methods/move_params'
 require 'grape-swagger/doc_methods/build_model_definition'
 require 'grape-swagger/doc_methods/version'
+require 'grape-swagger/doc_methods/webhooks'
+require 'grape-swagger/doc_methods/output_builder'
 
 module GrapeSwagger
   module DocMethods
@@ -37,38 +39,18 @@ module DocMethods
         specific_api_documentation: { desc: 'Swagger compatible API description for specific API' },
         endpoint_auth_wrapper: nil,
         swagger_endpoint_guard: nil,
-        token_owner: nil
+        token_owner: nil,
+        # OpenAPI version: nil (Swagger 2.0), '3.0', or '3.1'
+        openapi_version: nil,
+        # OpenAPI 3.1 specific options
+        json_schema_dialect: nil,
+        webhooks: nil
       }.freeze
 
     FORMATTER_METHOD = %i[format default_format default_error_formatter].freeze
 
     def self.output_path_definitions(combi_routes, endpoint, target_class, options)
-      output = endpoint.swagger_object(
-        target_class,
-        endpoint.request,
-        options
-      )
-
-      paths, definitions   = endpoint.path_and_definition_objects(combi_routes, options)
-      tags                 = tags_from(paths, options)
-
-      output[:tags]        = tags unless tags.empty? || paths.blank?
-      output[:paths]       = paths unless paths.blank?
-      output[:definitions] = definitions unless definitions.blank?
-
-      output
-    end
-
-    def self.tags_from(paths, options)
-      tags = GrapeSwagger::DocMethods::TagNameDescription.build(paths)
-
-      if options[:tags]
-        names = options[:tags].map { |t| t[:name] }
-        tags.reject! { |t| names.include?(t[:name]) }
-        tags += options[:tags]
-      end
-
-      tags
+      OutputBuilder.build(combi_routes, endpoint, target_class, options)
     end
 
     def hide_documentation_path

lib/grape-swagger/doc_methods/build_model_definition.rb

@@ -7,12 +7,20 @@ class << self
         def build(_model, properties, required, other_def_properties = {})
           definition = { type: 'object', properties: properties }.merge(other_def_properties)
 
-          definition[:required] = required if required.is_a?(Array) && required.any?
+          if required.is_a?(Array) && required.any?
+            # Filter required to only include properties that actually exist
+            # (handles hidden properties that are removed from properties but left in required)
+            property_keys = properties.keys.map(&:to_s)
+            valid_required = required.select { |r| property_keys.include?(r.to_s) }
+            definition[:required] = valid_required if valid_required.any?
+          end
 
           definition
         end
 
         def parse_params_from_model(parsed_response, model, model_name)
+          return parsed_response.to_h if parsed_response.is_a?(GrapeSwagger::OpenAPI::Schema)
+
           if parsed_response.is_a?(Hash) && parsed_response.keys.first == :allOf
             refs_or_models = parsed_response[:allOf]
             parsed = parse_refs_and_models(refs_or_models, model)

lib/grape-swagger/doc_methods/data_type.rb

@@ -48,15 +48,9 @@ def parse_multi_type(raw_data_type)
         end
 
         def parse_entity_name(model)
-          if model.respond_to?(:entity_name)
-            model.entity_name
-          elsif model.to_s.end_with?('::Entity', '::Entities')
-            model.to_s.split('::')[0..-2].join('_')
-          elsif model.to_s.start_with?('Entity::', 'Entities::', 'Representable::')
-            model.to_s.split('::')[1..-1].join('_')
-          else
-            model.to_s.split('::').join('_')
-          end
+          return model.entity_name if model.respond_to?(:entity_name)
+
+          GrapeSwagger.schema_name_generator.call(model)
         end
 
         def request_primitive?(type)