Fix #44: description not rendered for non-array entity references

[numbata]

Summary

Fixes #44

In OpenAPI/Swagger 2.0 and 3.0.x, $ref cannot have sibling properties - they are ignored by tools like Swagger-UI. This caused:

• desc (description) on non-array entity references to not be displayed
• readOnly flags to be ignored

The fix wraps $ref in allOf when description or readOnly is present:

Before (invalid - siblings ignored):

{ "$ref": "#/definitions/Address", "description": "Client address" }

After (valid OpenAPI):

{ "allOf": [{ "$ref": "#/definitions/Address" }], "description": "Client address" }

Array entity references were not affected because the description is a sibling to type and items, not $ref.

[github-actions]

Danger Report

No issues found.

View run

[Copilot]

Pull request overview

Fixes Swagger/OpenAPI rendering for entity properties that reference another schema via $ref by ensuring description and readOnly are not ignored by tooling.

Changes:

• Wraps $ref in allOf when desc (description) or read_only is provided for non-array entity references.
• Adds a dedicated regression spec for issue #44 and updates existing specs to match the new schema shape.
• Updates RuboCop auto-gen config to account for the new spec and updated file metrics.

Reviewed changes

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

Show a summary per file

File	Description
lib/grape-swagger/entity/parser.rb	Wraps $ref in allOf when adding description/readOnly to keep OpenAPI-compatible output.
spec/issues/44_desc_in_entity_type_spec.rb	New regression spec covering non-array $ref + desc and $ref + readOnly, plus array control case.
spec/grape-swagger/entity/parser_spec.rb	Updates expectations to assert allOf wrapping for referenced entities with descriptions.
spec/grape-swagger/entities/response_model_spec.rb	Updates expected generated swagger definitions to reflect allOf wrapping for $ref siblings.
.rubocop_todo.yml	Adds exclusion for new spec and updates thresholds per regenerated RuboCop todo.

---

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