Document Swagger metadata with the existing Representable parser

.github/workflows/test-mongodb.yml

@@ -5,18 +5,18 @@ permissions:
   contents: read
 jobs:
   test:
-    runs-on: ubuntu-latest
+    runs-on: ${{ matrix.entry.os || 'ubuntu-latest' }}
     strategy:
       fail-fast: false
       matrix:
         entry:
           - { ruby: '3.3', mongoid: '~> 6.4.8', mongodb: '6.0', grape: '~> 1.7.0', rack: '~> 2.2', coverage: false }
           - { ruby: '3.3', mongoid: '~> 6.4.8', mongodb: '6.0', grape: '~> 2.0.0', coverage: true }
           - { ruby: '3.3', mongoid: '~> 7.5.4', mongodb: '7.0', grape: '~> 2.4', coverage: false }
-          - { ruby: '3.3', mongoid: '~> 8.1.11', mongodb: '8.0', grape: '~> 2.4', coverage: false }
-          - { ruby: '3.3', mongoid: '~> 8.1.11', mongodb: '8.0', grape: '~> 3.0', coverage: false }
-          - { ruby: '3.4', mongoid: '~> 9.1', mongodb: '8.0', grape: '~> 4.0', coverage: true }
-          - { ruby: '4.0', mongoid: '~> 9.1', mongodb: '8.0', grape: '~> 4.0', coverage: false }
+          - { ruby: '3.3', mongoid: '~> 8.1.11', mongodb: '8.0', grape: '~> 2.4', coverage: false, os: 'ubuntu-22.04' }
+          - { ruby: '3.3', mongoid: '~> 8.1.11', mongodb: '8.0', grape: '~> 3.0', coverage: false, os: 'ubuntu-22.04' }
+          - { ruby: '3.4', mongoid: '~> 9.1', mongodb: '8.0', grape: '~> 4.0', coverage: true, os: 'ubuntu-22.04' }
+          - { ruby: '4.0', mongoid: '~> 9.1', mongodb: '8.0', grape: '~> 4.0', coverage: false, os: 'ubuntu-22.04' }
     name: test (ruby=${{ matrix.entry.ruby }}, mongoid=${{ matrix.entry.mongoid }}, mongodb=${{ matrix.entry.mongodb }}, grape=${{ matrix.entry.grape }})
     env:
       MONGOID_VERSION: ${{ matrix.entry.mongoid }}

CHANGELOG.md

@@ -10,6 +10,7 @@
 * [#45](https://github.com/ruby-grape/grape-roar/pull/45): Document native array rendering with Roar's collection factory while preserving collection envelopes and request-aware links - [@dblock](https://github.com/dblock).
 * [#46](https://github.com/ruby-grape/grape-roar/pull/46): Document Grape's built-in representer lookup through model Entity constants and API-local decorator mappings, including explicit overrides - [@dblock](https://github.com/dblock).
 * [#48](https://github.com/ruby-grape/grape-roar/pull/48): Document presenter parameter types using Grape's custom parsing contract with explicit input validation and writable properties; keep legacy test bundles on JSON 2.x for MultiJson compatibility - [@dblock](https://github.com/dblock).
+* [#47](https://github.com/ruby-grape/grape-roar/pull/47): Document Swagger response metadata using the optional grape-swagger-representable parser and Roar decorators; run MongoDB 8.0 CI jobs on Ubuntu 22.04 to avoid unsupported Linux kernels - [@dblock](https://github.com/dblock).
 * Your contribution here.
 
 ### 0.5.0 (2025/09/25)

CONTRIBUTING.md

@@ -32,7 +32,7 @@ bundle install
 bundle exec rake
 ```
 
-GitHub Actions tests Grape 1.x through 4.x. The core matrix includes Ruby 2.7 with Grape 1.x/2.x, Ruby 3.3 with every Grape major, and Ruby 3.4/4.0 with Grape 4.x. The ruby-head job is allowed to fail. Ruby 2.7 uses Ubuntu 22.04; newer Rubies use the latest Ubuntu runner.
+GitHub Actions tests Grape 1.x through 4.x. The core matrix includes Ruby 2.7 with Grape 1.x/2.x, Ruby 3.3 with every Grape major, and Ruby 3.4/4.0 with Grape 4.x. The ruby-head job is allowed to fail. Ruby 2.7 and MongoDB 8.0 jobs use Ubuntu 22.04; other jobs use the latest Ubuntu runner. MongoDB 8.0 cannot start on Linux kernels 6.19 and newer ([SERVER-121912](https://jira.mongodb.org/browse/SERVER-121912)), which can appear on rolling `ubuntu-latest` runners.
 
 Select dependency versions with `GRAPE_VERSION`, `RACK_VERSION`, `ACTIVERECORD_VERSION`, and `MONGOID_VERSION`. Resolve the bundle again when changing versions:
 

README.md

@@ -21,6 +21,7 @@ Use [Roar](https://github.com/apotonick/roar) with [Grape](https://github.com/in
   - [Accessing the Request Inside a Representer](#accessing-the-request-inside-a-representer)
   - [Decorators](#decorators)
   - [Presenter Parameter Types](#presenter-parameter-types)
+  - [Swagger Documentation](#swagger-documentation)
   - [Nested Representers](#nested-representers)
   - [Caching Representations](#caching-representations)
   - [Relation Extensions](#relation-extensions)
@@ -277,6 +278,42 @@ Send a JSON body such as `{"product":{"title":"Lonestar"}}` with `Content-Type:
 
 Roar properties and Swagger response metadata do not automatically define required fields, validation, or a model constructor. Keep input validation explicit, use a separate input representer when writable fields differ from output fields, and do not add a generic parser that guesses which model to construct. `from_hash` returns the represented model, so return the decorator explicitly from `.parse` when using the decorator as the parameter type.
 
+### Swagger Documentation
+
+The optional [grape-swagger-representable](https://github.com/Bugagazavr/grape-swagger-representable) parser documents Roar decorator classes. Add it and grape-swagger to your application's Gemfile; neither is required for rendering:
+
+```ruby
+gem 'grape-swagger'
+gem 'grape-swagger-representable'
+```
+
+Require the parser before calling `add_swagger_documentation`. Declare response field metadata under each property's `documentation:` option:
+
+```ruby
+require 'grape-swagger-representable'
+
+class ProductRepresenter < Grape::Roar::Decorator
+  include Roar::JSON
+
+  property :id, documentation: { type: Integer, desc: 'Product ID' }
+  property :title, documentation: { type: String, desc: 'Product title' }
+end
+
+class ProductsAPI < Grape::API
+  format :json
+  formatter :json, Grape::Formatter::Roar
+
+  desc 'Get a product', success: ProductRepresenter
+  get 'product/:id' do
+    present Product.find(params[:id]), with: ProductRepresenter
+  end
+
+  add_swagger_documentation
+end
+```
+
+`/swagger_doc/product` describes an integer `id` and string `title`, including their descriptions, while `/product/:id` renders the same properties with Roar. The parser registers decorator classes, not representer modules; use a decorator for a documented response model. Response documentation does not validate incoming parameters, and custom links, getters, and envelopes still need schemas that match their actual output.
+
 ### Nested Representers
 
 Use `property` for a single nested object and `collection` for multiple objects, specifying the representer at each level with `extend:`. For example, notifications can contain comments, posts, and images: