grape-oas 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 1a578224c8df0f07ef5151db8496a084a64c6000f1f4c4158d7cc21efee1f91f
+  data.tar.gz: a1427ab277998cd7828e24c91f2555be6ea41b254312f14c4ad40b43204fa13c
+SHA512:
+  metadata.gz: c03fa30c214a62b2f3164ced48ff16e6c8ba120126ac3d7397db0cd0a7e6ee191224b10bd59badb91f848d3bfcded18cc03e4da331f883c80203795dfa0a143b
+  data.tar.gz: b232aa12c2211dc35853933ad09e1d1d5451d1df9fc3c2e1cb2c3bc1d58f8769b892141381323669c3c158e6ca409bbab3358012f9be0360f2736cb6194b1ada

data/CHANGELOG.md

@@ -0,0 +1,82 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.0] - 2025-12-06
+
+### Added
+
+#### Core Features
+- OpenAPI specification generation for Grape APIs
+- Support for OpenAPI 2.0 (Swagger), 3.0, and 3.1 specifications
+- `GrapeOAS.generate(app:, schema_type:)` for programmatic generation
+- `add_oas_documentation` DSL for mounting documentation endpoint
+- `add_swagger_documentation` compatibility shim for grape-swagger migration
+- Query parameter `?oas=2|3|3.1` for version selection at runtime
+
+#### Entity Support
+- Built-in Grape::Entity introspection (no separate gem needed)
+- Dry::Validation::Contract and Dry::Struct support
+- Entity inheritance with `allOf` composition
+- Polymorphism support with `discriminator`
+- Sum types (`|`) converted to `anyOf`
+- Circular reference handling with `$ref`
+
+#### Parameter Documentation
+- All Grape parameter types (String, Integer, Float, Boolean, Date, DateTime, Array, Hash, File)
+- Nested parameters (Hash with block)
+- Array parameters with item types (`Array[String]`, `Array[Integer]`)
+- Multi-type parameters (`types: [String, Integer]`)
+- Parameter validation constraints (values, regexp, minimum, maximum, etc.)
+- Parameter hiding (`documentation: { hidden: true }`)
+- `collectionFormat` support for OAS2 arrays
+
+#### Response Documentation
+- `success` and `failure` response definitions
+- Multiple success/failure status codes
+- Response headers
+- Response examples
+- Multiple present responses with `as:` key combination
+- Root element wrapping support
+- `suppress_default_error_response` option
+
+#### Endpoint Documentation
+- `desc` block syntax with detail, tags, deprecated, consumes, produces
+- Endpoint hiding (`hidden: true` or lambda)
+- `body_name` for custom body parameter naming (OAS2)
+- Request body for GET/HEAD/DELETE when explicitly enabled
+- Operation extensions (`x-*` properties)
+
+#### Configuration
+- Global options: host, base_path, schemes, servers, consumes, produces
+- Info object: title, version, description, contact, license, terms_of_service
+- Security definitions (API key, OAuth2, Bearer)
+- Tag definitions with descriptions
+- `models` option to pre-register entities
+- Namespace filtering for partial schema generation
+- URL-based namespace filtering for mounted docs (`/swagger_doc/users`)
+- Tag filtering to only include used tags
+
+#### Rake Tasks
+- `grape_oas:generate[API,schema_type,output_path]` for file generation
+- `grape_oas:validate[file_path]` for spec validation
+
+#### Migration Support
+- Comprehensive migration guide from grape-swagger
+- Feature parity documentation
+- Compatibility shim for `add_swagger_documentation`
+
+#### Extensibility
+- Introspector registry - register custom introspectors via `GrapeOAS.introspectors.register()`
+- Exporter registry - register custom exporters via `GrapeOAS.exporters.register(ExporterClass, as: :alias)`
+
+### Documentation
+- README with full usage examples
+- `docs/MIGRATING_FROM_GRAPE_SWAGGER.md` - detailed migration guide
+- `docs/ARCHITECTURE.md` - system architecture overview
+- `docs/INTROSPECTORS.md` - introspector system documentation
+- `docs/EXPORTERS.md` - exporter system documentation
+- `docs/API_MODEL.md` - internal API model reference

data/CONTRIBUTING.md

@@ -0,0 +1,87 @@
+# Contributing to Grape::OAS
+
+We welcome contributions to Grape::OAS! This document provides guidelines for contributing.
+
+## Getting Started
+
+1. **Fork the repository** on GitHub
+
+2. **Clone your fork**:
+   ```bash
+   git clone https://github.com/YOUR_USERNAME/grape-oas.git
+   cd grape-oas
+   ```
+
+3. **Set up upstream remote**:
+   ```bash
+   git remote add upstream https://github.com/numbata/grape-oas.git
+   ```
+
+4. **Install dependencies**:
+   ```bash
+   bin/setup
+   ```
+
+## Development Workflow
+
+1. **Create a topic branch**:
+   ```bash
+   git checkout -b my-feature
+   ```
+
+2. **Write tests** for your changes in `test/`
+
+3. **Implement your feature or fix**
+
+4. **Run the test suite**:
+   ```bash
+   bundle exec rake test
+   ```
+
+5. **Run RuboCop**:
+   ```bash
+   bundle exec rubocop
+   ```
+
+6. **Run all checks**:
+   ```bash
+   bundle exec rake
+   ```
+
+## Submitting Changes
+
+1. **Update CHANGELOG.md** under "Unreleased" section
+
+2. **Write clear commit messages** describing what and why
+
+3. **Push to your fork**:
+   ```bash
+   git push origin my-feature
+   ```
+
+4. **Open a Pull Request** against the `main` branch
+
+## Pull Request Guidelines
+
+- Keep PRs focused on a single change
+- Include tests for new functionality
+- Update documentation if needed
+- Ensure CI passes before requesting review
+
+## Code Style
+
+- Follow existing code conventions
+- RuboCop enforces style - run it before committing
+- Use descriptive variable and method names
+
+## Testing
+
+- Write tests for all new functionality
+- Ensure existing tests pass
+- Aim for good coverage of edge cases
+
+## Questions?
+
+Open an issue for questions or discussions about potential changes.
+
+Thank you for contributing!

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Andrei Subbota
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,184 @@
+# Grape::OAS
+
+[![Gem Version](https://badge.fury.io/rb/grape-oas.svg)](https://badge.fury.io/rb/grape-oas)
+[![CI](https://github.com/numbata/grape-oas/actions/workflows/ci.yml/badge.svg)](https://github.com/numbata/grape-oas/actions)
+
+OpenAPI Specification (OAS) documentation generator for [Grape](https://github.com/ruby-grape/grape) APIs. Supports OpenAPI 2.0 (Swagger), 3.0, and 3.1 specifications.
+
+## Why Grape::OAS?
+
+Grape::OAS is built around a **DTO (Data Transfer Object) architecture** that separates collecting API metadata from generating schemas. This clean separation makes the codebase easier to reason about and enables support for multiple output formats (OAS 2.0, 3.0, 3.1) from the same API definition.
+
+## Features
+
+- **Multi-version support**: Generate OAS 2.0, 3.0, or 3.1 from the same API
+- **Entity integration**: Works with [grape-entity](https://github.com/ruby-grape/grape-entity) and [dry-struct](https://dry-rb.org/gems/dry-struct/)
+- **Automatic type inference**: Derives OpenAPI types from Grape parameter definitions
+- **Flexible output**: Mount as an endpoint or generate programmatically
+
+## Compatibility
+
+| grape-oas | grape | grape-entity | dry-struct | Ruby |
+|-----------|-------|--------------|------------|------|
+| 0.1.x | >= 3.0 | >= 0.7 | >= 1.0 | >= 3.2 |
+
+## Installation
+
+```ruby
+gem 'grape-oas'
+```
+
+For entity support:
+
+```ruby
+gem 'grape-entity'  # For grape-entity support
+gem 'dry-struct'    # For dry-struct contract support
+```
+
+## Quick Start
+
+### Mount Documentation Endpoint
+
+```ruby
+class API < Grape::API
+  format :json
+
+  add_oas_documentation(
+    info: {
+      title: 'My API',
+      version: '1.0.0'
+    }
+  )
+
+  resource :users do
+    desc 'List users', entity: Entity::User
+    get { User.all }
+  end
+end
+```
+
+Documentation available at:
+- `/swagger_doc` - OpenAPI 3.0 (default)
+- `/swagger_doc?oas=2` - OpenAPI 2.0
+- `/swagger_doc?oas=3.1` - OpenAPI 3.1
+
+### Manual Generation
+
+```ruby
+# Generate OpenAPI 3.0 spec
+spec = GrapeOAS.generate(app: API, schema_type: :oas3)
+puts JSON.pretty_generate(spec)
+```
+
+### Rake Tasks
+
+```ruby
+# In Rakefile
+require 'grape_oas/tasks'
+```
+
+```bash
+rake grape_oas:generate[MyAPI,oas31,spec/openapi.json]
+```
+
+## Documentation
+
+| Document | Description |
+|----------|-------------|
+| [Configuration](docs/CONFIGURATION.md) | All configuration options |
+| [Usage Guide](docs/USAGE.md) | Detailed usage examples |
+| [Architecture](docs/ARCHITECTURE.md) | System architecture overview |
+| [Introspectors](docs/INTROSPECTORS.md) | Custom introspector development |
+| [Exporters](docs/EXPORTERS.md) | Custom exporter development |
+| [API Model](docs/API_MODEL.md) | Internal API model reference |
+
+## Basic Usage
+
+### Documenting Endpoints
+
+```ruby
+desc 'Get a user by ID',
+  detail: 'Returns detailed user information',
+  tags: ['users']
+
+params do
+  requires :id, type: Integer, desc: 'User ID'
+end
+
+get ':id' do
+  User.find(params[:id])
+end
+```
+
+### Response Documentation
+
+```ruby
+desc 'Get user' do
+  success Entity::User
+  failure [[404, 'Not Found'], [500, 'Server Error']]
+end
+```
+
+### Entity Definition
+
+```ruby
+class Entity::User < Grape::Entity
+  expose :id, documentation: { type: Integer }
+  expose :name, documentation: { type: String }
+  expose :posts, using: Entity::Post, documentation: { is_array: true }
+end
+```
+
+## Extensibility
+
+### Custom Introspectors
+
+```ruby
+class MyModelIntrospector
+  extend GrapeOAS::Introspectors::Base
+
+  def self.handles?(subject)
+    subject.is_a?(Class) && subject < MyBaseModel
+  end
+
+  def self.build_schema(subject, stack: [], registry: {})
+    GrapeOAS::ApiModel::Schema.new(type: "object", canonical_name: subject.name)
+  end
+end
+
+GrapeOAS.introspectors.register(MyModelIntrospector)
+```
+
+### Custom Exporters
+
+```ruby
+GrapeOAS.exporters.register(MyCustomExporter, as: :custom)
+schema = GrapeOAS.generate(app: API, schema_type: :custom)
+```
+
+## Related Projects
+
+| Project | Description |
+|---------|-------------|
+| [grape](https://github.com/ruby-grape/grape) | REST-like API framework for Ruby |
+| [grape-entity](https://github.com/ruby-grape/grape-entity) | Entity exposure for Grape APIs |
+| [grape-swagger](https://github.com/ruby-grape/grape-swagger) | OpenAPI documentation for Grape APIs |
+| [grape-swagger-entity](https://github.com/ruby-grape/grape-swagger-entity) | grape-swagger adapter for grape-entity |
+| [oas_grape](https://github.com/a-chacon/oas_grape) | Another OpenAPI 3.1 generator for Grape |
+
+## Development
+
+```bash
+git clone https://github.com/numbata/grape-oas.git
+cd grape-oas
+bin/setup
+bundle exec rake test
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/numbata/grape-oas. See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+## License
+
+MIT License. Copyright (c) Andrei Subbota.

data/RELEASING.md

@@ -0,0 +1,109 @@
+# Releasing Grape::OAS
+
+This document describes the release process for the grape-oas gem.
+
+## Pre-Release Checks
+
+Before releasing, ensure:
+
+1. All tests pass locally and in CI:
+   ```bash
+   bundle install
+   bundle exec rake
+   ```
+
+2. The CHANGELOG.md is up to date with all changes since the last release.
+
+3. The version number in `lib/grape_oas/version.rb` is correct.
+
+## Release Steps
+
+### Automated Release Process
+
+1. **Update the version** in `lib/grape_oas/version.rb` to the release version
+
+2. **Prepare the CHANGELOG**:
+   ```bash
+   bundle exec rake release:prerelease
+   ```
+   This task will:
+   - Replace "Unreleased" with the version number and today's date
+   - Remove any "Your contribution here" placeholder lines
+   - Commit with message "Preparing for release vX.X.X"
+
+   **Note**: The task is idempotent - safe to run multiple times.
+
+3. **Push and create the release**:
+   ```bash
+   git push origin main
+   bundle exec rake release
+   ```
+   This will:
+   - Build the gem
+   - Create a git tag
+   - Push the tag to GitHub
+   - Push the gem to RubyGems.org
+
+<details>
+<summary>Manual Release Steps (if needed)</summary>
+
+1. **Update CHANGELOG.md**
+   - Change "Unreleased" to the version number and date
+   - Remove any "Your contribution here" placeholder lines
+
+2. **Commit the release preparation**:
+   ```bash
+   git add CHANGELOG.md
+   git commit -m "Preparing for release v0.x.x"
+   git push origin main
+   ```
+
+3. **Create and push the release**:
+   ```bash
+   bundle exec rake release
+   ```
+   This will:
+   - Build the gem
+   - Create a git tag
+   - Push the tag to GitHub
+   - Push the gem to RubyGems.org
+</details>
+
+## Post-Release
+
+You can automate the post-release preparation with:
+
+```bash
+bundle exec rake release:postrelease
+git push origin main
+```
+
+This task will:
+- Bump the patch version in `lib/grape_oas/version.rb`
+- Ensure CHANGELOG.md has an "Unreleased" section
+- Commit the changes with message "Prepare for next development iteration"
+
+**Note**: The task is idempotent - safe to run multiple times without duplicating work.
+
+<details>
+<summary>Manual Post-Release Steps (if needed)</summary>
+
+1. **Prepare for next development cycle**:
+   - Add "Unreleased" section to CHANGELOG.md
+   - Bump version in `lib/grape_oas/version.rb`
+
+2. **Commit post-release changes**:
+   ```bash
+   git add CHANGELOG.md lib/grape_oas/version.rb
+   git commit -m "Prepare for next development iteration"
+   git push origin main
+   ```
+</details>
+
+## Versioning
+
+This project follows [Semantic Versioning](https://semver.org/):
+
+- **MAJOR**: Incompatible API changes
+- **MINOR**: New functionality in a backward compatible manner
+- **PATCH**: Backward compatible bug fixes

data/grape-oas.gemspec

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require_relative "lib/grape_oas/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "grape-oas"
+  spec.version = GrapeOAS::VERSION
+  spec.authors = ["Andrei Subbota"]
+  spec.email = ["subbota@gmail.com"]
+
+  spec.summary = "OpenAPI (Swagger) v2 and v3 documentation for Grape APIs"
+  spec.description = "A Grape extension that provides OpenAPI (Swagger) v2 and v3 documentation support"
+  spec.homepage = "https://github.com/numbata/grape-oas"
+  spec.license = "MIT"
+  spec.required_ruby_version = ">= 3.2"
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = spec.homepage
+  spec.metadata["changelog_uri"] = "#{spec.homepage}/blob/main/CHANGELOG.md"
+
+  spec.files = Dir["lib/**/*", "*.md", "LICENSE.txt", "grape-oas.gemspec"]
+
+  spec.add_dependency "grape", ">= 3.0"
+  spec.add_dependency "zeitwerk"
+
+  spec.metadata["rubygems_mfa_required"] = "true"
+end

data/lib/grape-oas.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require "grape_oas"

data/lib/grape_oas/api_model/api.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module GrapeOAS
+  module ApiModel
+    # Represents the root API object in the DTO model for OpenAPI v2/v3.
+    # Contains metadata, paths, servers, tags, and components.
+    # Used as the entry point for building OpenAPIv2 and OpenAPIv3 documents.
+    #
+    # @see https://swagger.io/specification/
+    # @see GrapeOAS::ApiModel::Path
+    class API < Node
+      attr_accessor :title, :version, :paths, :servers, :tag_defs, :components,
+                    :host, :base_path, :schemes, :security_definitions, :security,
+                    :registered_schemas, :suppress_default_error_response
+
+      def initialize(title:, version:)
+        super()
+        @title      = title
+        @version    = version
+        @paths      = Set.new
+        @servers    = []
+        @tag_defs   = Set.new
+        @components = {}
+        @host       = nil
+        @base_path  = nil
+        @schemes    = []
+        @security_definitions = {}
+        @security = []
+        @registered_schemas = []
+        @suppress_default_error_response = false
+      end
+
+      def add_path(path)
+        @paths << path
+      end
+
+      def add_tags(*tags)
+        @tag_defs.merge(tags)
+      end
+    end
+  end
+end

data/lib/grape_oas/api_model/media_type.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module GrapeOAS
+  module ApiModel
+    # Represents a media type (e.g., application/json) in the DTO model for OpenAPI v2/v3.
+    # Used for request bodies and responses to specify content type and schema.
+    #
+    # @see https://swagger.io/specification/
+    # @see GrapeOAS::ApiModel::RequestBody, GrapeOAS::ApiModel::Response
+    class MediaType < Node
+      attr_accessor :mime_type, :schema, :examples, :extensions
+
+      def initialize(mime_type:, schema:, examples: nil, extensions: nil)
+        super()
+        @mime_type = mime_type
+        @schema    = schema
+        @examples  = examples
+        @extensions = extensions
+      end
+    end
+  end
+end

data/lib/grape_oas/api_model/node.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module GrapeOAS
+  module ApiModel
+    # Base class for all DTO (intermediate) nodes used in OpenAPI v2/v3 conversion.
+    # Provides a unique ID and helper methods for referencing and bucketing.
+    # All DTO classes for OpenAPIv2 and OpenAPIv3 inherit from Node.
+    #
+    # @abstract
+    # @see GrapeOAS::ApiModel::Schema, GrapeOAS::ApiModel::Parameter, etc.
+    class Node
+      # OpenAPI component bucket names per spec (some are irregular plurals)
+      BUCKET_NAMES = {
+        "Schema" => "schemas",
+        "Parameter" => "parameters",
+        "RequestBody" => "requestBodies",
+        "Response" => "responses",
+        "Header" => "headers",
+        "SecurityScheme" => "securitySchemes",
+        "Link" => "links",
+        "Callback" => "callbacks",
+        "Example" => "examples",
+        "PathItem" => "pathItems"
+      }.freeze
+
+      class << self
+        # Returns the pluralized bucket name for this class (e.g., "schemas", "parameters").
+        # Uses OpenAPI spec-compliant names for irregular plurals (e.g., "requestBodies").
+        # Memoized at the class level to avoid repeated string manipulation.
+        def bucket
+          @bucket ||= begin
+            class_name = name.split("::").last
+            BUCKET_NAMES.fetch(class_name, "#{class_name.downcase}s")
+          end
+        end
+      end
+
+      attr_reader :id
+
+      def initialize(node_id: nil)
+        @id = node_id || generate_id
+      end
+
+      def ref
+        "#/components/#{self.class.bucket}/#{id}"
+      end
+
+      private
+
+      def generate_id
+        SecureRandom.uuid
+      end
+    end
+  end
+end