From 477d1c463c177482a1c70b4e4b5c42cd94fc4efb Mon Sep 17 00:00:00 2001 From: "Daniel (dB.) Doubrovkine" Date: Tue, 27 Oct 2026 06:25:31 -0400 Subject: [PATCH] Document optional Swagger response metadata for Roar decorators Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .github/workflows/test-mongodb.yml | 10 ++++---- CHANGELOG.md | 1 + CONTRIBUTING.md | 2 +- README.md | 37 ++++++++++++++++++++++++++++++ 4 files changed, 44 insertions(+), 6 deletions(-) diff --git a/.github/workflows/test-mongodb.yml b/.github/workflows/test-mongodb.yml index fc623f1..14204d0 100644 --- a/.github/workflows/test-mongodb.yml +++ b/.github/workflows/test-mongodb.yml @@ -5,7 +5,7 @@ permissions: contents: read jobs: test: - runs-on: ubuntu-latest + runs-on: ${{ matrix.entry.os || 'ubuntu-latest' }} strategy: fail-fast: false matrix: @@ -13,10 +13,10 @@ jobs: - { 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 }} diff --git a/CHANGELOG.md b/CHANGELOG.md index ce597e9..c539963 100644 --- a/CHANGELOG.md +++ b/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) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ed5970f..71837fc 100644 --- a/CONTRIBUTING.md +++ b/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: diff --git a/README.md b/README.md index fde9edf..ba58bef 100644 --- a/README.md +++ b/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: