versponse 0.5.0 → 0.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 3e41e92ddddd696555389adf93be562fe44e04c9ef919ed966e2a5e6a8971f71
4
- data.tar.gz: 8045646699279ac701fc372a14235b0034dcb7334505ede2396bc8f6393d84dd
3
+ metadata.gz: 025ca4572e82cdf832e61ceea0d84959bbb9c548bd4919f4ab5acc3fd5380c30
4
+ data.tar.gz: 47bbfaf82b0035de693eec7d0e762b34b554d5521060534d7939956e89440754
5
5
  SHA512:
6
- metadata.gz: 51baf5d319a769e66b0ef698c8b3cb38cf0bb8db84c8c2b7cb23272c85e9bfbaadce391094b4a478bbb81f69cb3395ad75c70874bd8d2c22553f32120a61c205
7
- data.tar.gz: aedeeacc29e64833c3fc5c67ba6c0f309bda3521aec035607ac25b342a4927cdd2470dd35356a1b99ce95b008ce8ca3c61f7a130217c3d0a97a4c2e4dc8da960
6
+ metadata.gz: 6967286f2de9d33406ed1c8bcd43dd73c84511f0e9702a34b8766a744885380b48353fcbe2e5090b0c607ba0a3e9323fd73f635cad4e4731ebb411716da5ad08
7
+ data.tar.gz: 0a5c71d053a6a7b0a1051d6b34cbfb92658a53fb5a2edde5b890b77b38e042b805019c7e44ecb728e5a79a64a707699717598e4f274c2c97f1aeb087ab9a0701
data/CHANGELOG.md CHANGED
@@ -1,5 +1,15 @@
1
1
  ## [Unreleased]
2
2
 
3
+ ## [0.6.0] - 2026-11-17
4
+
5
+ ### Added
6
+
7
+ - In OpenAPI documents, `wrapper` takes a `root_description:`, which describes the property under the root: the array of a collection wrapper, or the `$ref` of a single one, wrapped in `allOf` in OpenAPI 3.0 documents. Without it, the output is unchanged. `to_schema` takes the same `root_description:` beside `root:`.
8
+
9
+ ### Changed
10
+
11
+ - In OpenAPI documents, `wrapper` raises `Versponse::DefinitionError` for a `description:` that isn't a non-empty String, and for `root: "meta"` beside `meta:`, whose `$ref` replaced the response. `to_schema` and `serialize` raise for that root and meta too, and both raise `ArgumentError` for `meta:` beside `root: false`. `serialize(root: false)` renders unwrapped, as `serialize_json` does, instead of under a `"false"` key. A `meta:` error from `wrapper` names the wrapper.
12
+
3
13
  ## [0.5.0] - 2026-11-11
4
14
 
5
15
  ### Changed
data/README.md CHANGED
@@ -114,7 +114,7 @@ ContactResponse.serialize_json(contacts) # {"cont
114
114
  ContactResponse.serialize_json(contact, root: false) # {...}
115
115
  ```
116
116
 
117
- `root:` overrides the declared root. `serialize` never uses it, so data for CSV or webhook payloads stays unwrapped. Without ActiveSupport, `root` needs `collection:`. Subclasses don't inherit a root, and `root_key` and `collection_root_key` read it.
117
+ `root:` overrides the declared root, and `root: "meta"` beside `meta:` raises `Versponse::DefinitionError`. `serialize` never uses the declared root, so data for CSV or webhook payloads stays unwrapped. Without ActiveSupport, `root` needs `collection:`. Subclasses don't inherit a root, and `root_key` and `collection_root_key` read it.
118
118
 
119
119
  ## Properties
120
120
 
@@ -406,7 +406,7 @@ PriceListResponse.to_schema(version: "2025-09")
406
406
  - `to_ref(view:, property: nil)` returns `"#/components/schemas/<name>"`. An anonymous class has no component name, so it raises `Versponse::DefinitionError`.
407
407
  - With `discriminator:`, `one_of` emits an OpenAPI `mapping` built from each variant's `const`, such as `{"order" => "#/components/schemas/OrderResponse"}`. A variant without that `const`, or two variants with the same value, raise `DefinitionError` when the schema is built.
408
408
  - A `one_of` is a `oneOf`, in documents and validation schemas alike, except an expandable `one_of`, which is an `anyOf` of each variant's full shape and its inline collapsed shape. Without `discriminator:`, its variants need shapes a client can tell apart: if one payload fits two variants, `oneOf` rejects it, so `validate_output` raises and strict consumers such as rswag's response validation fail. For polymorphic responses, prefer `discriminator:`.
409
- - `to_schema(root: "unit_types", meta: MetaResponse, collection: true)` returns a wrapper schema for the whole response body. The envelope is strict (`additionalProperties: false`) whatever `default_additional_properties` says.
409
+ - `to_schema(root: "unit_types", meta: MetaResponse, collection: true)` returns a wrapper schema for the whole response body. `root_description:` describes the property under the root, as `wrapper` does in OpenAPI documents. The envelope is strict (`additionalProperties: false`) whatever `default_additional_properties` says.
410
410
  - `description` and `schema_options` on a class reach its subclasses, so an abstract `ApplicationResponse` can carry them. Versponse looks them up when it builds schemas, so a later change to the parent still applies. A subclass's `schema_options` merge with its ancestors', and the subclass wins per key. A version's own `description` and `schema_options` win over both.
411
411
  - Collapsed shapes are strict (`additionalProperties: false`) whatever `default_additional_properties` says, so only a real collapsed payload matches them.
412
412
 
@@ -428,7 +428,8 @@ class PublicApiDocument < Versponse::OpenAPI::Document
428
428
 
429
429
  responses namespace: PublicApi
430
430
  requests namespace: PublicApi # verquest body requests
431
- wrapper :contact_list, PublicApi::ContactResponse, collection: true, meta: PublicApi::MetaResponse, description: "List of Contacts" # component "ContactList", under the class's collection root
431
+ wrapper :contact_list, PublicApi::ContactResponse, collection: true, meta: PublicApi::MetaResponse, description: "List of Contacts", # component "ContactList", under the class's collection root
432
+ root_description: "Contacts on this page."
432
433
 
433
434
  schema "Error", ERROR_SCHEMA # hand-written components, collision-checked
434
435
  webhooks { |version| Webhooks.openapi(version) }
@@ -443,7 +444,7 @@ PublicApiDocument.validate(version: "2025-09") # => [] when valid OpenAPI and
443
444
  - Values use OpenAPI's own key names, which are never camelized. The exception is `schema`: a hand-written component is a schema, so its keys are camelized like every other schema (`additional_properties:` becomes `additionalProperties`). Keys inside `properties` and a discriminator's `mapping`, values of `enum`, `example`, and `default`, and `x-` extensions keep their spelling.
444
445
  - A block that takes an argument receives the version. A `finalize` block that takes one argument receives only the document.
445
446
  - `responses` and `requests` take one or more classes, or `namespace:` with a Module or a String. At build, Versponse eager-loads the namespace through Zeitwerk, so its classes don't have to be loaded first. An undefined namespace, or one with no response classes or body requests, raises `Versponse::DefinitionError`. So does a listed class of the wrong kind, or a listed request whose `location` isn't `:body`.
446
- - `wrapper` turns a Symbol name into PascalCase (`:contact_list` declares `ContactList`) and uses a String as given. Its `meta:` takes a response class, whose `$ref` describes `"meta"`, and anything else raises `Versponse::DefinitionError`. `serialize(meta:)` takes the Hash instead. `root:` defaults to the class's declared root, the collection root with `collection: true`, and `description:` sets the wrapper schema's description. `wrapper_names` lists the declared wrapper components.
447
+ - `wrapper` turns a Symbol name into PascalCase (`:contact_list` declares `ContactList`) and uses a String as given. Its `meta:` takes a response class, whose `$ref` describes `"meta"`, and anything else raises `Versponse::DefinitionError`. `serialize(meta:)` takes the Hash instead. `root:` defaults to the class's declared root, the collection root with `collection: true`, and `description:` sets the wrapper schema's description. `root: "meta"` beside `meta:` raises `Versponse::DefinitionError`, since `meta:` describes that key. `root_description:` takes a String and sets the description of the property under the root: the array with `collection: true`, otherwise the `$ref`, which OpenAPI 3.0 documents wrap in `allOf` because 3.0 ignores keywords next to a `$ref`. Without it, the property has no description. Both descriptions take a non-empty String, and anything else raises `Versponse::DefinitionError`. `wrapper_names` lists the declared wrapper components.
447
448
  - `ref(name)` returns the `$ref` of a wrapper or `schema` the document declares, like a response class's `to_ref`: `PublicApiDocument.ref(:ContactList)` returns `"#/components/schemas/ContactList"`. A name the document doesn't declare, its parents included, raises `Versponse::DefinitionError`, so a typo fails when the spec loads.
448
449
  - `ref` turns a Symbol into PascalCase as `wrapper` does, so `:ContactList` and `:contact_list` name the same component. Spell the Symbol as the component is named, so the spec matches the generated document. A String is used as given. `component_name(name)` returns the name without the `#/components/schemas/` prefix.
449
450
  - `server` and `tag` write keywords that start with `x_` as extensions, with every underscore turned into a hyphen: `x_internal: true` becomes `"x-internal" => true`, and `x_display_name:` becomes `"x-display-name"`.
@@ -27,6 +27,7 @@ module Versponse
27
27
  # @param fields [Array<String, Symbol>, nil] dotted paths of the fields to render (identifiers and consts always
28
28
  # render), "*" or nil for all
29
29
  # @raise [ArgumentError] without a version or with meta: but no root:
30
+ # @raise [Versponse::DefinitionError] for root: "meta" beside meta:
30
31
  # @raise [Versponse::InvalidExpandError] for unknown expand paths (config.unknown_expand = :raise)
31
32
  # @raise [Versponse::InvalidFieldsError] for unknown paths or paths outside the collapsed shape of unexpanded associations
32
33
  # (config.unknown_fields = :raise)
@@ -34,7 +35,11 @@ module Versponse
34
35
  # @raise [Versponse::ViewNotFoundError] for an unknown or nil view
35
36
  # @raise [Versponse::ExtractionError] when reading a value fails
36
37
  def serialize(object, version: nil, view: :default, context: EMPTY_CONTEXT, root: nil, meta: nil, expand: nil, fields: nil)
37
- raise ArgumentError, "meta: requires root:" if meta && root.nil?
38
+ if meta
39
+ raise ArgumentError, "meta: requires root:" unless root
40
+
41
+ Wrapper.check_root!(root, meta)
42
+ end
38
43
  raise ViewNotFoundError, "view: can't be nil; the default view is :default" if view.nil?
39
44
 
40
45
  context ||= EMPTY_CONTEXT
@@ -116,14 +121,20 @@ module Versponse
116
121
  # @param root [String, Symbol, nil] builds a wrapper schema with the response under this key
117
122
  # @param meta [Class, nil] class whose $ref describes "meta" (requires root:)
118
123
  # @param collection [Boolean] the root key holds an array
124
+ # @param root_description [String, nil] description of the property under the root (requires root:)
119
125
  # @return [Hash] frozen schema
120
- # @raise [ArgumentError] with meta: but no root:
121
- # @raise [Versponse::DefinitionError] for a meta: that isn't a class with a $ref
126
+ # @raise [ArgumentError] with meta: or root_description: but no root:
127
+ # @raise [Versponse::DefinitionError] for a meta: that isn't a class with a $ref, root: "meta" beside meta:, or a
128
+ # root_description: that isn't a non-empty String
122
129
  # @raise [Versponse::VersionNotFoundError] when the class, or a Versponse meta: class, doesn't serve the version
123
130
  # @raise [Versponse::ViewNotFoundError] for an unknown view (wrappers too)
124
- def to_schema(version: nil, view: :default, root: nil, meta: nil, collection: false)
131
+ def to_schema(version: nil, view: :default, root: nil, meta: nil, collection: false, root_description: nil)
125
132
  Wrapper.check_meta!(meta)
126
- raise ArgumentError, "meta: requires root:" if meta && root.nil?
133
+ raise ArgumentError, "meta: requires root:" if meta && !root
134
+ raise ArgumentError, "root_description: requires root:" if root_description && !root
135
+
136
+ Wrapper.check_root!(root, meta)
137
+ Wrapper.check_description!(:root_description, root_description)
127
138
 
128
139
  versponse.requesting(version) do |canonical|
129
140
  next versponse.openapi_schema(version: canonical, view:) unless root
@@ -131,7 +142,7 @@ module Versponse
131
142
  # The wrapper only refers to the components, but their versions and the view must exist like for any schema
132
143
  versponse.resolve(canonical).properties_for(view)
133
144
  meta.versponse.resolve(canonical) if References.versponse?(meta)
134
- DeepFreeze.call(Wrapper.schema(self, view:, root:, meta:, collection:))
145
+ DeepFreeze.call(Wrapper.schema(self, view:, root:, meta:, collection:, root_description:))
135
146
  end
136
147
  end
137
148
 
@@ -2,5 +2,5 @@
2
2
 
3
3
  module Versponse
4
4
  # Gem version (Versponse::Version is the version definition class)
5
- GEM_VERSION = "0.5.0"
5
+ GEM_VERSION = "0.6.0"
6
6
  end
@@ -92,7 +92,8 @@ module Versponse
92
92
  @declarations.wrappers.each_value do |wrapper|
93
93
  next unless Components.resolved(wrapper.klass, @version)
94
94
 
95
- schema = wrapper.klass.to_schema(version: @version, view: wrapper.view, root: wrapper.root, meta: wrapper.meta, collection: wrapper.collection)
95
+ schema = wrapper.klass.to_schema(version: @version, view: wrapper.view, root: wrapper.root, meta: wrapper.meta, collection: wrapper.collection,
96
+ root_description: wrapper.root_description)
96
97
  schema = schema.merge("description" => wrapper.description).freeze if wrapper.description
97
98
  set.add(wrapper.name, schema, "wrapper #{wrapper.name}")
98
99
  end
@@ -9,7 +9,7 @@ module Versponse
9
9
  # One response or request source: an explicit list, or a namespace (Module or String) resolved at build
10
10
  Source = Data.define(:classes, :namespace)
11
11
  # One named wrapper component
12
- Wrapper = Data.define(:name, :klass, :root, :collection, :meta, :view, :description)
12
+ Wrapper = Data.define(:name, :klass, :root, :collection, :meta, :view, :description, :root_description)
13
13
 
14
14
  # @return [String, nil] rswag key prefix
15
15
  attr_accessor :document_name
@@ -151,14 +151,27 @@ module Versponse
151
151
  declarations.request_sources << source(:requests, classes.flatten, namespace)
152
152
  end
153
153
 
154
- def wrapper(name, klass, root: nil, collection: false, meta: nil, view: :default, description: nil)
155
- Versponse::Wrapper.check_meta!(meta)
154
+ def wrapper(name, klass, root: nil, collection: false, meta: nil, view: :default, description: nil, root_description: nil)
156
155
  name = declared_name(name)
156
+ naming_wrapper(name) do
157
+ Versponse::Wrapper.check_meta!(meta)
158
+ Versponse::Wrapper.check_description!(:description, description)
159
+ Versponse::Wrapper.check_description!(:root_description, root_description)
160
+ end
157
161
  root ||= declared_root(klass, collection)
158
162
  raise DefinitionError, "wrapper #{name} needs root: or a #{klass} that declares root" unless root
159
163
 
164
+ naming_wrapper(name) { Versponse::Wrapper.check_root!(root, meta) }
165
+
160
166
  declarations.claim!(:wrapper, name)
161
- declarations.wrappers[name] = Declarations::Wrapper.new(name:, klass:, root:, collection:, meta:, view:, description:)
167
+ declarations.wrappers[name] = Declarations::Wrapper.new(name:, klass:, root:, collection:, meta:, view:, description:, root_description:)
168
+ end
169
+
170
+ # Prefixes a DefinitionError with the wrapper's name
171
+ def naming_wrapper(name)
172
+ yield
173
+ rescue DefinitionError => error
174
+ raise DefinitionError, "wrapper #{name} #{error.message}"
162
175
  end
163
176
 
164
177
  def schema(name, value = nil, &block)
@@ -14,6 +14,24 @@ module Versponse
14
14
  raise DefinitionError, %(meta: takes a response class, whose $ref describes "meta"; serialize(meta:) takes the Hash)
15
15
  end
16
16
 
17
+ # @param root [String, Symbol, nil] key holding the response
18
+ # @param meta [Object, nil] meta: given for a wrapper schema
19
+ # @return [void]
20
+ # @raise [Versponse::DefinitionError] when root: is "meta" beside meta:, whose $ref would replace the response
21
+ def self.check_root!(root, meta)
22
+ raise DefinitionError, %(root: "meta" clashes with meta:, which describes "meta") if meta && root.to_s == "meta"
23
+ end
24
+
25
+ # @param keyword [Symbol] option name, for the message
26
+ # @param value [Object] description given
27
+ # @return [void]
28
+ # @raise [Versponse::DefinitionError] unless value is nil or a non-empty String
29
+ def self.check_description!(keyword, value)
30
+ return if value.nil? || (value.is_a?(String) && !value.empty?)
31
+
32
+ raise DefinitionError, "#{keyword}: must be a non-empty String, got #{value.inspect}"
33
+ end
34
+
17
35
  # The envelope is strict (additionalProperties: false) whatever config.default_additional_properties says
18
36
  #
19
37
  # @param klass [Class] response class
@@ -21,10 +39,12 @@ module Versponse
21
39
  # @param root [String, Symbol] key holding the response
22
40
  # @param meta [Class, nil] class whose $ref describes "meta"
23
41
  # @param collection [Boolean] the root key holds an array
42
+ # @param root_description [String, nil] description of the property under the root
24
43
  # @return [Hash] wrapper schema
25
- def self.schema(klass, view:, root:, meta:, collection:)
44
+ def self.schema(klass, view:, root:, meta:, collection:, root_description: nil)
26
45
  item = {"$ref" => klass.to_ref(view:)}
27
- properties = {root.to_s => collection ? {"type" => "array", "items" => item} : item}
46
+ property = collection ? {"type" => "array", "items" => item} : item
47
+ properties = {root.to_s => root_description ? described(property, root_description) : property}
28
48
  properties["meta"] = {"$ref" => meta.to_ref} if meta
29
49
  {"type" => "object", "required" => properties.keys, "properties" => properties, "additionalProperties" => false}
30
50
  end
@@ -34,13 +54,20 @@ module Versponse
34
54
  # @param meta [Hash, nil] added under "meta" with String keys
35
55
  # @return [Hash, Array<Hash>] data, or the wrapper Hash
36
56
  def self.wrap(data, root:, meta:)
37
- return data if root.nil?
57
+ return data unless root
38
58
 
39
59
  wrapped = {root.to_s => data}
40
60
  wrapped["meta"] = string_keys(meta) if meta
41
61
  wrapped
42
62
  end
43
63
 
64
+ # OpenAPI 3.0 ignores keywords next to a $ref, so a bare $ref is wrapped in allOf, as Properties::Reference does
65
+ def self.described(property, description)
66
+ property = {"allOf" => [property]} if property.key?("$ref") && Versponse.configuration.nullable_keyword?
67
+ property.merge("description" => description)
68
+ end
69
+ private_class_method :described
70
+
44
71
  def self.string_keys(value)
45
72
  case value
46
73
  when Hash then value.to_h { |key, item| [key.to_s, string_keys(item)] }
metadata CHANGED
@@ -1,7 +1,7 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: versponse
3
3
  version: !ruby/object:Gem::Version
4
- version: 0.5.0
4
+ version: 0.6.0
5
5
  platform: ruby
6
6
  authors:
7
7
  - Petr Hlavicka