grape-swagger-entity 0.7.0 → 0.7.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3d55e877c4ed7f40cbc6331e38fdb62522c85e92dfcb5bbf239be8181cbcd456
-  data.tar.gz: c22441830ec45ee2ef82dff6066106bfecfd5a820050665090e4c4f9c110b16e
+  metadata.gz: 30e014da1f2cee91b947f2028660fcad2f9d71102bbe30d4eff6369a48974949
+  data.tar.gz: 4e6d460b2a210c5356a99444b89ca8dec5ded34b1601a4200e01ac4e7d84d68e
 SHA512:
-  metadata.gz: bbf329848abcdcef57edd7cde491cef96160f29e266958f9ad5763f987210d506811858937c4e9cee59d85e2ff3ad200e85834a2cece230a172d22a6b0aaa2c9
-  data.tar.gz: efe0f9739a54925a044661d02ecd9ba232a5909a9c08556bd5a51c39aa6ea82ab413db5e77a350659ccba75462ceba704efb95f02ce2f774ea762f3491d8460c
+  metadata.gz: 4830b3a7de51a5391ff090594e70bdb492c722bbcdc6e88745f169b22dc417a64291facee0fb465b3488804a81c113beb6b0f8f5b84f4204b69c9c108b5e3b89
+  data.tar.gz: 0b029af3078ad8c0769177445a2ed698292ba7f77fd910134dd8274f8d4d5d0f0354d2130916a78cc687aa44b36af797a503055052c9ea30808eaf0a0fbec63e

data/.github/workflows/danger-comment.yml

@@ -0,0 +1,10 @@
+name: Danger Comment
+on:
+  workflow_run:
+    workflows: [Danger]
+    types: [completed]
+
+jobs:
+  comment:
+    uses: numbata/danger-pr-comment/.github/workflows/danger-comment.yml@main
+    secrets: inherit

data/.github/workflows/danger.yml

@@ -1,21 +1,11 @@
-name: danger
-on: pull_request
+name: Danger
+on:
+  pull_request:
+    types: [opened, reopened, edited, synchronize]
 
 jobs:
   danger:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-        with:
-          fetch-depth: 100
-      - name: Set up Ruby
-        uses: ruby/setup-ruby@v1
-        with:
-          ruby-version: 3.2
-          bundler-cache: true
-          rubygems: latest
-      - name: Run Danger
-        run: |
-          # the token is public, has public_repo scope and belongs to the grape-bot user owned by @dblock, this is ok
-          TOKEN=$(echo -n Z2hwX2lYb0dPNXNyejYzOFJyaTV3QUxUdkNiS1dtblFwZTFuRXpmMwo= | base64 --decode)
-          DANGER_GITHUB_API_TOKEN=$TOKEN bundle exec danger --verbose
+    uses: numbata/danger-pr-comment/.github/workflows/danger-run.yml@main
+    secrets: inherit
+    with:
+      ruby-version: "3.2"

data/.rspec

@@ -1,2 +1,3 @@
 --format documentation
 --color
+--require "spec_helper"

data/.rubocop_todo.yml

@@ -6,12 +6,14 @@
 # Note that changes in the inspected code, or installation of new
 # versions of RuboCop, may require this file to be generated again.
 
-# Offense count: 3
+# Offense count: 8
 # Configuration parameters: AllowedMethods.
 # AllowedMethods: enums
 Lint/ConstantDefinitionInBlock:
   Exclude:
     - 'spec/grape-swagger/entities/response_model_spec.rb'
+    - 'spec/issues/44_desc_in_entity_type_spec.rb'
+    - 'spec/issues/962_polymorphic_entity_with_custom_documentation_spec.rb'
     - 'spec/support/shared_contexts/inheritance_api.rb'
     - 'spec/support/shared_contexts/this_api.rb'
 
@@ -21,6 +23,11 @@ Lint/EmptyBlock:
   Exclude:
     - 'spec/grape-swagger/entity/attribute_parser_spec.rb'
 
+# Offense count: 1
+Lint/EmptyClass:
+  Exclude:
+    - 'spec/support/shared_contexts/custom_type_parser.rb'
+
 # Offense count: 2
 # This cop supports unsafe autocorrection (--autocorrect-all).
 # Configuration parameters: AllowedMethods.
@@ -37,7 +44,7 @@ Metrics/AbcSize:
 # Offense count: 2
 # Configuration parameters: CountComments, CountAsOne.
 Metrics/ClassLength:
-  Max: 117
+  Max: 145
 
 # Offense count: 2
 # Configuration parameters: AllowedMethods, AllowedPatterns.
@@ -79,11 +86,12 @@ RSpec/ContextWording:
     - 'spec/support/shared_contexts/inheritance_api.rb'
     - 'spec/support/shared_contexts/this_api.rb'
 
-# Offense count: 2
+# Offense count: 3
 # Configuration parameters: IgnoredMetadata.
 RSpec/DescribeClass:
   Exclude:
     - '**/spec/features/**/*'
+    - '**/spec/issues/**/*'
     - '**/spec/requests/**/*'
     - '**/spec/routing/**/*'
     - '**/spec/system/**/*'
@@ -93,12 +101,13 @@ RSpec/DescribeClass:
 # Offense count: 4
 # Configuration parameters: CountAsOne.
 RSpec/ExampleLength:
-  Max: 213
+  Max: 225
 
-# Offense count: 26
+# Offense count: 30
 RSpec/LeakyConstantDeclaration:
   Exclude:
     - 'spec/grape-swagger/entities/response_model_spec.rb'
+    - '**/spec/issues/**/*'
     - 'spec/support/shared_contexts/inheritance_api.rb'
     - 'spec/support/shared_contexts/this_api.rb'
 

data/AGENTS.md

@@ -0,0 +1,24 @@
+# grape-swagger-entity
+
+Adapter for grape-swagger that parses Grape::Entity classes into OpenAPI schema definitions.
+
+## Quick Reference
+
+```bash
+bundle install          # Install dependencies
+bundle exec rspec       # Run tests
+bundle exec rubocop     # Run linter
+bundle exec rubocop -a  # Auto-fix linter issues
+```
+
+## Key Constraints
+
+- Ruby >= 3.0
+- All files must start with `# frozen_string_literal: true`
+- CHANGELOG.md entry required for every PR (danger enforces this)
+
+## Documentation
+
+- [Testing Patterns](docs/testing.md)
+- [Contributing Guidelines](docs/contributing.md)
+- [Architecture Overview](docs/architecture.md)

data/CHANGELOG.md

@@ -1,3 +1,17 @@
+### 0.7.1 (2026/01/28)
+
+#### Features
+
+* [#91](https://github.com/ruby-grape/grape-swagger-entity/pull/91): Improve README and add documentation structure - [@numbata](https://github.com/numbata).
+
+#### Fixes
+
+* [#90](https://github.com/ruby-grape/grape-swagger-entity/pull/90): Fix description not rendered for non-array entity references - [@numbata](https://github.com/numbata).
+* [#86](https://github.com/ruby-grape/grape-swagger-entity/pull/86): Fix Array[Object] documentation type parsing - [@numbata](https://github.com/numbata).
+* [#87](https://github.com/ruby-grape/grape-swagger-entity/pull/87): Remove hidden attributes from required - [@bogdan](https://github.com/bogdan).
+* [#88](https://github.com/ruby-grape/grape-swagger-entity/pull/88): Update danger workflows - [@numbata](https://github.com/numbata).
+* [#89](https://github.com/ruby-grape/grape-swagger-entity/pull/89): Remove ruby-grape-danger - [@dblock](https://github.com/dblock).
+
 ### 0.7.0 (2025/08/02)
 
 #### Features

data/Dangerfile

@@ -1,3 +1,6 @@
 # frozen_string_literal: true
 
-danger.import_dangerfile(gem: 'ruby-grape-danger')
+danger.import_dangerfile(gem: 'danger-pr-comment')
+
+changelog.check!
+toc.check!

data/Gemfile

@@ -43,7 +43,10 @@ group :development do
 end
 
 group :test do
+  gem 'danger', require: false
+  gem 'danger-changelog', require: false
+  gem 'danger-pr-comment', require: false
+  gem 'danger-toc', require: false
   gem 'grape-entity', grape_entity_spec
-  gem 'ruby-grape-danger', '~> 0.2.1', require: false
   gem 'simplecov', require: false
 end

data/README.md

@@ -6,15 +6,64 @@
 ## Table of Contents
 
 - [What is grape-swagger-entity?](#what-is-grape-swagger-entity)
+  - [What it does](#what-it-does)
+  - [Example Output](#example-output)
+- [Related Projects](#related-projects)
+- [Compatibility](#compatibility)
 - [Installation](#installation)
+- [Usage](#usage)
+  - [Basic Entity](#basic-entity)
+  - [Custom Model Description](#custom-model-description)
+  - [Entity References](#entity-references)
+  - [Documentation Options](#documentation-options)
 - [Development](#development)
 - [Contributing](#contributing)
 - [License](#license)
 
-
 ## What is grape-swagger-entity?
 
-A simple grape-swagger adapter to allow parse representers as response model
+This gem provides an adapter for [grape-swagger](https://github.com/ruby-grape/grape-swagger) that allows parsing [grape-entity](https://github.com/ruby-grape/grape-entity) classes to generate OpenAPI/Swagger model definitions automatically.
+
+### What it does
+
+- Generates `definitions` in your Swagger JSON from Grape::Entity exposures
+- Maps entity properties to OpenAPI schema properties with types and descriptions
+- Handles nested entities and entity references via `$ref`
+- Supports arrays, required fields, and documentation options
+
+### Example Output
+
+```json
+{
+  "definitions": {
+    "User": {
+      "type": "object",
+      "description": "User model",
+      "properties": {
+        "id": { "type": "integer", "description": "User ID" },
+        "name": { "type": "string", "description": "Full name" }
+      },
+      "required": ["id", "name"]
+    }
+  }
+}
+```
+
+## Related Projects
+
+- [Grape](https://github.com/ruby-grape/grape)
+- [Grape Entity](https://github.com/ruby-grape/grape-entity)
+- [Grape Swagger](https://github.com/ruby-grape/grape-swagger)
+- [Grape Swagger Representable](https://github.com/ruby-grape/grape-swagger-representable)
+
+## Compatibility
+
+This gem is tested with the following versions:
+
+| grape-swagger-entity | grape-swagger | grape-entity | grape   |
+|---------------------|---------------|--------------|---------|
+| 0.7.x               | >= 2.0.0      | >= 1.0.0     | >= 1.3  |
+| 0.6.x               | >= 1.2.0      | >= 0.6.0     | >= 1.3  |
 
 ## Installation
 
@@ -32,17 +81,63 @@ Or install it yourself as:
 
     $ gem install grape-swagger-entity
 
-## Development
+## Usage
+
+### Basic Entity
+
+Define your entities with `documentation` options to generate OpenAPI schema properties:
+
+```ruby
+class UserEntity < Grape::Entity
+  expose :id, documentation: { type: Integer, desc: 'User ID' }
+  expose :name, documentation: { type: String, desc: 'Full name' }
+  expose :email, documentation: { type: String, desc: 'Email address' }
+end
+```
+
+### Custom Model Description
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rspec` to run the tests. You can also run `bin/pry` for an interactive prompt that will allow you to experiment.
+Override the default "{ModelName} model" description by defining a `self.documentation` method. This feature is handled by [grape-swagger](https://github.com/ruby-grape/grape-swagger) (requires grape-swagger >= 2.2.0):
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+```ruby
+class UserEntity < Grape::Entity
+  def self.documentation
+    { desc: 'Represents a user account with profile information' }
+  end
+
+  expose :id, documentation: { type: Integer, desc: 'User ID' }
+  expose :name, documentation: { type: String, desc: 'Full name' }
+end
+```
+
+### Entity References
+
+Use `using:` to reference other entities and `is_array:` for collections:
+
+```ruby
+class OrderEntity < Grape::Entity
+  expose :id, documentation: { type: Integer, desc: 'Order ID' }
+  expose :user, using: UserEntity,
+         documentation: { desc: 'The customer who placed this order' }
+  expose :items, using: ItemEntity,
+         documentation: { desc: 'Line items', is_array: true }
+end
+```
+
+### Documentation Options
+
+Common options: `type`, `desc`, `required`, `is_array`, `values`, `example`.
+
+See [full documentation options](docs/documentation-options.md) for all available options including validation constraints.
+
+## Development
+
+See [testing documentation](docs/testing.md) for development setup and running tests.
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/ruby-grape/grape-swagger-entity.
+See [contributing guidelines](docs/contributing.md).
 
 ## License
 
 The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).
-

data/docs/architecture.md

@@ -0,0 +1,71 @@
+# Architecture Overview
+
+## Purpose
+
+This gem registers a model parser with grape-swagger that converts `Grape::Entity` classes into OpenAPI schema definitions.
+
+## Core Components
+
+```
+lib/grape-swagger/entity/
+├── parser.rb           # Main parser - converts Entity to OpenAPI schema
+├── attribute_parser.rb # Parses individual exposure attributes
+├── helper.rb           # Utility methods for model naming, discriminators
+└── version.rb          # Gem version
+```
+
+### Parser (`parser.rb`)
+
+Entry point for entity parsing. Responsibilities:
+- Extract exposures from Grape::Entity
+- Handle nested entities and `using:` references
+- Process `merge: true` exposures
+- Handle inheritance with `allOf` and discriminators
+- Determine required fields
+
+### AttributeParser (`attribute_parser.rb`)
+
+Converts individual exposure options to OpenAPI property schema:
+- Maps Ruby types to OpenAPI types
+- Handles arrays (`is_array: true`)
+- Processes enums (`values:`)
+- Adds constraints (min/max, minLength/maxLength)
+
+### Helper (`helper.rb`)
+
+Utilities for:
+- Model name resolution (strips Entity/Entities suffix)
+- Discriminator detection for inheritance
+- Root exposure extraction
+
+## Data Flow
+
+```
+Grape::Entity class
+       │
+       ▼
+   Parser.call
+       │
+       ├── extract_params (get exposures)
+       │
+       ├── parse_grape_entity_params
+       │         │
+       │         ├── AttributeParser (per exposure)
+       │         │
+       │         └── parse_nested (for nested blocks)
+       │
+       └── handle_discriminator (inheritance)
+       │
+       ▼
+[properties_hash, required_array]
+```
+
+## Integration Point
+
+Registered with grape-swagger in `lib/grape-swagger/entity.rb`:
+
+```ruby
+GrapeSwagger.model_parsers.register(GrapeSwagger::Entity::Parser, Grape::Entity)
+```
+
+grape-swagger calls `Parser.new(model, endpoint).call` when it encounters a `Grape::Entity` subclass.

data/docs/contributing.md

@@ -0,0 +1,57 @@
+# Contributing Guidelines
+
+## PR Requirements
+
+Every PR must include:
+
+1. **CHANGELOG.md entry** - Add under `### X.X.X (Next)` in the appropriate section:
+   ```markdown
+   #### Fixes
+   * [#123](https://github.com/ruby-grape/grape-swagger-entity/pull/123): Brief description - [@username](https://github.com/username).
+   ```
+
+2. **Passing CI** - RuboCop + RSpec must pass
+
+3. **Tests** - New functionality needs specs; bug fixes need regression tests
+
+## CHANGELOG Format
+
+```markdown
+### 0.7.1 (Next)
+
+#### Features
+
+* Your contribution here.
+
+#### Fixes
+
+* [#PR](URL): Description - [@author](URL).
+```
+
+- Use `Features` for new functionality
+- Use `Fixes` for bug fixes and maintenance
+
+## Commit Messages
+
+Follow conventional style:
+- `Fix #123: description` for bug fixes
+- `Add feature description` for features
+- `Update dependency/docs` for maintenance
+
+## Code Style
+
+RuboCop enforces style. Key rules:
+- `frozen_string_literal: true` pragma required
+- Consistent hash indentation
+- No trailing whitespace
+
+```bash
+bundle exec rubocop -a  # Auto-fix most issues
+```
+
+## Danger Checks
+
+CI runs danger which enforces:
+- CHANGELOG entry present
+- Table of Contents in README is current
+- PR has description

data/docs/documentation-options.md

@@ -0,0 +1,89 @@
+# Documentation Options
+
+The `documentation` hash in entity exposures supports the following options:
+
+## Type Options
+
+| Option | Description | Example |
+|--------|-------------|---------|
+| `type` | OpenAPI data type | `String`, `Integer`, `Boolean`, `Float`, `Date`, `DateTime` |
+| `is_array` | Marks field as array type | `true` / `false` |
+
+## Description Options
+
+| Option | Description | Example |
+|--------|-------------|---------|
+| `desc` | Property description | `'User email address'` |
+| `example` | Example value for documentation | `'user@example.com'` |
+| `default` | Default value | `'pending'` |
+
+## Validation Options
+
+| Option | Description | Example |
+|--------|-------------|---------|
+| `required` | Whether field is required | `true` / `false` |
+| `values` | Enum values (array or proc) | `%w[pending active]` or `-> { Status.all }` |
+| `minimum` | Minimum value for numeric types | `0` |
+| `maximum` | Maximum value for numeric types | `100` |
+| `min_length` | Minimum length for strings | `1` |
+| `max_length` | Maximum length for strings | `255` |
+| `min_items` | Minimum items for arrays | `1` |
+| `max_items` | Maximum items for arrays | `10` |
+| `unique_items` | Array items must be unique | `true` |
+
+## Display Options
+
+| Option | Description | Example |
+|--------|-------------|---------|
+| `read_only` | Marks field as read-only | `true` |
+| `hidden` | Hide field from documentation | `true` |
+
+## Examples
+
+### Basic types
+
+```ruby
+expose :id, documentation: { type: Integer, desc: 'Unique identifier' }
+expose :name, documentation: { type: String, desc: 'Full name', required: true }
+expose :active, documentation: { type: Boolean, default: true }
+```
+
+### Enums
+
+```ruby
+expose :status, documentation: {
+  type: String,
+  desc: 'Current status',
+  values: %w[pending active suspended]
+}
+```
+
+### Numeric constraints
+
+```ruby
+expose :age, documentation: {
+  type: Integer,
+  minimum: 0,
+  maximum: 150
+}
+```
+
+### String constraints
+
+```ruby
+expose :username, documentation: {
+  type: String,
+  min_length: 3,
+  max_length: 20
+}
+```
+
+### Arrays
+
+```ruby
+expose :tags, documentation: {
+  type: String,
+  is_array: true,
+  desc: 'Associated tags'
+}
+```

data/docs/testing.md

@@ -0,0 +1,63 @@
+# Testing Patterns
+
+## Running Tests
+
+```bash
+bundle exec rspec                    # Run all tests
+bundle exec rspec spec/path/file.rb  # Run specific file
+bundle exec rspec -e "description"   # Run matching examples
+```
+
+## Test Structure
+
+```
+spec/
+├── grape-swagger/
+│   ├── entity_spec.rb              # Main module specs
+│   ├── entity/
+│   │   ├── parser_spec.rb          # Parser unit tests
+│   │   └── attribute_parser_spec.rb
+│   └── entities/
+│       └── response_model_spec.rb  # Integration tests
+├── issues/                          # Regression tests for GitHub issues
+│   └── 962_polymorphic_entity_...   # Named by issue number
+└── support/
+    └── shared_contexts/             # Reusable test setup
+```
+
+## Shared Contexts
+
+Use shared contexts for common API setups:
+
+```ruby
+require 'spec_helper'
+require_relative '../../support/shared_contexts/this_api'
+
+describe SomeClass do
+  include_context 'this api'
+  # ...
+end
+```
+
+## Issue Regression Tests
+
+When fixing a bug, create a spec in `spec/issues/` named `{issue_number}_{brief_description}_spec.rb`:
+
+```ruby
+# spec/issues/123_some_bug_spec.rb
+require 'spec_helper'
+
+describe '#123 brief description of the issue' do
+  # Test that reproduces and verifies the fix
+end
+```
+
+## Testing with Different Gem Versions
+
+Environment variables control dependency versions:
+
+```bash
+GRAPE_VERSION=2.0.0 bundle update grape
+GRAPE_SWAGGER_VERSION=HEAD bundle update grape-swagger
+GRAPE_ENTITY_VERSION=1.0.1 bundle update grape-entity
+```

data/lib/grape-swagger/entity/attribute_parser.rb

@@ -20,7 +20,7 @@ module GrapeSwagger
         documentation = entity_options[:documentation]
         return param if documentation.nil?
 
-        add_array_documentation(param, documentation) if documentation[:is_array]
+        add_array_documentation(param, documentation) if array_type?(documentation)
 
         add_attribute_sample(param, documentation, :default)
         add_attribute_sample(param, documentation, :example)
@@ -37,11 +37,26 @@ module GrapeSwagger
       def model_from(entity_options)
         model = entity_options[:using] if entity_options[:using].present?
 
-        model ||= entity_options[:documentation][:type] if could_it_be_a_model?(entity_options[:documentation])
+        documentation = entity_options[:documentation]
+        model ||= documentation[:type] if could_it_be_a_model?(documentation)
 
         model
       end
 
+      # Checks if documentation indicates an array type that needs items wrapping.
+      # Returns true for:
+      #   - is_array: true (explicit flag)
+      #   - type: 'Array[Something]' (array with element type)
+      # Returns false for:
+      #   - type: 'Array' (bare array - already an array type, no wrapping needed)
+      def array_type?(documentation)
+        return false if documentation.nil?
+        return documentation[:is_array] if documentation.key?(:is_array)
+
+        # Only match Array[ElementType] syntax, not bare 'Array'
+        documentation[:type].to_s.match?(/\Aarray\[.+\]\z/i)
+      end
+
       def could_it_be_a_model?(value)
         return false if value.nil?
 
@@ -57,6 +72,8 @@ module GrapeSwagger
       end
 
       def primitive_type?(type)
+        return false if type.nil?
+
         data_type = GrapeSwagger::DocMethods::DataType.call(type)
         GrapeSwagger::DocMethods::DataType.request_primitive?(data_type)
       end
@@ -69,7 +86,7 @@ module GrapeSwagger
 
         documented_data_type = document_data_type(documentation, data_type)
 
-        if documentation[:is_array]
+        if array_type?(documentation)
           {
             type: :array,
             items: documented_data_type
@@ -97,7 +114,9 @@ module GrapeSwagger
       end
 
       def entity_model_type(name, entity_options)
-        if entity_options[:documentation] && entity_options[:documentation][:is_array]
+        documentation = entity_options[:documentation]
+
+        if array_type?(documentation)
           {
             'type' => 'array',
             'items' => {

data/lib/grape-swagger/entity/parser.rb

@@ -43,37 +43,72 @@ module GrapeSwagger
       def parse_grape_entity_params(params, parent_model = nil)
         return unless params
 
-        parsed = params.each_with_object({}) do |(entity_name, entity_options), memo|
-          documentation_options = entity_options.fetch(:documentation, {})
-          in_option = documentation_options.fetch(:in, nil).to_s
-          hidden_option = documentation_options.fetch(:hidden, nil)
-          next if in_option == 'header' || hidden_option == true
-
-          entity_name = entity_name.original if entity_name.is_a?(Alias)
-          final_entity_name = entity_options.fetch(:as, entity_name)
-          documentation = entity_options[:documentation]
-
-          memo[final_entity_name] = if entity_options[:nesting]
-                                      parse_nested(entity_name, entity_options, parent_model)
-                                    else
-                                      attribute_parser.call(entity_options)
-                                    end
-
-          next unless documentation
-
-          memo[final_entity_name][:readOnly] = documentation[:read_only].to_s == 'true' if documentation[:read_only]
-          memo[final_entity_name][:description] = documentation[:desc] if documentation[:desc]
+        required = required_params(params)
+        parsed_params = parse_params(params, parent_model)
+
+        handle_discriminator(parsed_params, required)
+      end
+
+      def parse_params(params, parent_model)
+        params.each_with_object({}) do |(entity_name, entity_options), memo|
+          next if skip_param?(entity_options)
+
+          original_entity_name = entity_name.is_a?(Alias) ? entity_name.original : entity_name
+          final_entity_name = entity_options.fetch(:as, original_entity_name)
+
+          memo[final_entity_name] = parse_entity_options(entity_options, original_entity_name, parent_model)
+          add_documentation_to_memo(memo[final_entity_name], entity_options[:documentation])
+        end
+      end
+
+      def skip_param?(entity_options)
+        documentation_options = entity_options.fetch(:documentation, {})
+        in_option = documentation_options.fetch(:in, nil).to_s
+        hidden_option = documentation_options.fetch(:hidden, nil)
+
+        in_option == 'header' || hidden_option == true
+      end
+
+      def parse_entity_options(entity_options, entity_name, parent_model)
+        if entity_options[:nesting]
+          parse_nested(entity_name, entity_options, parent_model)
+        else
+          attribute_parser.call(entity_options)
         end
+      end
+
+      def add_documentation_to_memo(memo_entry, documentation)
+        return unless documentation
+
+        has_read_only = documentation[:read_only]
+        has_description = documentation[:desc]
+
+        return unless has_read_only || has_description
+
+        # In OpenAPI/Swagger 2.0 and 3.0.x, $ref cannot have sibling properties - they are ignored.
+        # To add description or readOnly to a $ref, wrap it in allOf.
+        # See: https://swagger.io/docs/specification/using-ref/
+        wrap_ref_in_all_of(memo_entry) if memo_entry.key?('$ref')
 
+        memo_entry[:readOnly] = documentation[:read_only].to_s == 'true' if has_read_only
+        memo_entry[:description] = documentation[:desc] if has_description
+      end
+
+      def wrap_ref_in_all_of(memo_entry)
+        ref = memo_entry.delete('$ref')
+        memo_entry['allOf'] = [{ '$ref' => ref }]
+      end
+
+      def handle_discriminator(parsed, required)
         discriminator = GrapeSwagger::Entity::Helper.discriminator(model)
         if discriminator
-          respond_with_all_of(parsed, params, discriminator)
+          respond_with_all_of(parsed, required, discriminator)
         else
-          [parsed, required_params(params)]
+          [parsed, required]
         end
       end
 
-      def respond_with_all_of(parsed, params, discriminator)
+      def respond_with_all_of(parsed, required, discriminator)
         parent_name = GrapeSwagger::Entity::Helper.model_name(model.superclass, endpoint)
 
         {
@@ -83,7 +118,7 @@ module GrapeSwagger
             },
             [
               add_discriminator(parsed, discriminator),
-              required_params(params).push(discriminator.attribute)
+              required.push(discriminator.attribute)
             ]
           ]
         }
@@ -136,8 +171,11 @@ module GrapeSwagger
 
       def required_params(params)
         params.each_with_object(Set.new) do |(key, options), accum|
-          required = if options.fetch(:documentation, {}).key?(:required)
-                       options.dig(:documentation, :required)
+          documentation = options.fetch(:documentation, {})
+          next if documentation[:hidden]
+
+          required = if documentation.key?(:required)
+                       documentation[:required]
                      else
                        !options.key?(:if) && !options.key?(:unless) && options[:expose_nil] != false
                      end

data/lib/grape-swagger/entity/version.rb

@@ -2,6 +2,6 @@
 
 module GrapeSwagger
   module Entity
-    VERSION = '0.7.0'
+    VERSION = '0.7.1'
   end
 end

metadata

@@ -1,13 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: grape-swagger-entity
 version: !ruby/object:Gem::Version
-  version: 0.7.0
+  version: 0.7.1
 platform: ruby
 authors:
 - Kirill Zaitsev
+autorequire:
 bindir: exe
 cert_chain: []
-date: 1980-01-02 00:00:00.000000000 Z
+date: 2026-01-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: grape-entity
@@ -37,18 +38,21 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2'
+description:
 email:
 - kirik910@gmail.com
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".github/workflows/danger-comment.yml"
 - ".github/workflows/danger.yml"
 - ".github/workflows/test.yml"
 - ".gitignore"
 - ".rspec"
 - ".rubocop.yml"
 - ".rubocop_todo.yml"
+- AGENTS.md
 - CHANGELOG.md
 - Dangerfile
 - Gemfile
@@ -59,6 +63,10 @@ files:
 - UPGRADING.md
 - bin/pry
 - bin/setup
+- docs/architecture.md
+- docs/contributing.md
+- docs/documentation-options.md
+- docs/testing.md
 - grape-swagger-entity.gemspec
 - lib/grape-swagger-entity.rb
 - lib/grape-swagger/entity.rb
@@ -71,6 +79,7 @@ licenses:
 - MIT
 metadata:
   rubygems_mfa_required: 'true'
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -85,7 +94,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.8
+rubygems_version: 3.5.22
+signing_key:
 specification_version: 4
 summary: Grape swagger adapter to support grape-entity object parsing
 test_files: []