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 +4 -4
- data/CHANGELOG.md +10 -0
- data/README.md +5 -4
- data/lib/versponse/base/class_methods.rb +17 -6
- data/lib/versponse/gem_version.rb +1 -1
- data/lib/versponse/open_api/builder.rb +2 -1
- data/lib/versponse/open_api/declarations.rb +1 -1
- data/lib/versponse/open_api/document.rb +16 -3
- data/lib/versponse/wrapper.rb +30 -3
- metadata +1 -1
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
SHA256:
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: 025ca4572e82cdf832e61ceea0d84959bbb9c548bd4919f4ab5acc3fd5380c30
|
|
4
|
+
data.tar.gz: 47bbfaf82b0035de693eec7d0e762b34b554d5521060534d7939956e89440754
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
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
|
|
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
|
-
|
|
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
|
|
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
|
|
|
@@ -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)
|
data/lib/versponse/wrapper.rb
CHANGED
|
@@ -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
|
-
|
|
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
|
|
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)] }
|