sober_swag 0.23.0 → 0.25.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 13d3f48bc3d3d8fb42984b13e7b260f0c5e52331cbc6b641b600511b67aed323
-  data.tar.gz: 32437d0fc96f42c5c05120946154108d0ffa2a6d9ad3fce648c8c49884addbce
+  metadata.gz: 95eb8012259c21946fe6b6ab07aaa4da3b29f5d3746b0581d12a6f67b39f8f5c
+  data.tar.gz: d775af4081190de942d2e6d978a922dd37083c9d0a59638cd16259d1c9ad8295
 SHA512:
-  metadata.gz: 2e643f5d730c20eac9671c6e306f63c8c0b679dd26eab69a5eea91aa456c094f240399c7058d59300e7c333c3747980a814a7db43f979f2e800cdc9ef940f577
-  data.tar.gz: 4454eee231879d67313f1d9c1d1b094faf1131d3487f68d96fa1e529055ce48954ad8fa74eeef78b675baf7a4404afb778d607ce701b27a3e40bbeb513aaab15
+  metadata.gz: 669a66d91c6b2e6d47648a30d44829a5713ee4b0170626953359ed3df5b66f14b21ea76d84654ea4bcafb14f1fe622ce8ac8338de98df530a8d19ef47275fc0b
+  data.tar.gz: 92617f0c507187d52c88a07324fc0081503d5095c4bd7f192fb65d252c9dff38ae52da708f2e38665430f6f9d506703e1e1fdc95f4dc0b4c621a33ef577802a0

data/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## [v0.25.0] 2022-06-07
+
+- Adds more description to the error raised if you try to use a non-reporting output type as the output of a field
+- Add a lot more documentation for the reporting interface in [`docs/reporting.md`](docs/reporting.md)
+
+## [v0.24.1] 2022-05-26
+
+- Added a better `#message` to `SoberSwag::Reporting::Report::Error`
+
 ## [v0.22.0] 2021-12-21
 
 - Added `SoberSwag::Reporting`, which is basically a v2 of the gem!

data/docs/reporting.md

@@ -120,7 +120,7 @@ A view will *always inherit all attributes of the parent object, regardless of o
 class AlternativePersonOutput < SoberSwag::Output::Struct
   field :first_name, SoberSwag::Reporting::Output.text
 
-  view :with_grade do
+  define_view :with_grade do
     field :grade, SoberSwag::Reporting::Output.text.nilable do
       if object_to_serialize.respond_to?(:grade)
         object_to_serialize.grade
@@ -187,4 +187,329 @@ There are basically two things to keep in mind when upgrading to `SoberSwag::Rep
    Instead, view management is now *explicit*.
    This is because it was too tempting to pass data to serialize in the options key, which is against the point of the serializers.
 
+# API Overview
 
+This section presents an overview of the available reporting outputs and inputs.
+
+## `SoberSwag::Reporting::Output`
+
+This module contains reporting *outputs*.
+These act as type-checked serializers.
+
+### Primitive Types
+
+The following "primitive types" are available:
+
+- `SoberSwag::Reporting::Output.bool`, which returns a `SoberSwag::Reporting::Output::Bool`.
+  This type is for serializing boolean values, IE, `true` or `false`.
+  It will serialize the boolean directly to the JSON.
+- `SoberSwag::Reporting::Output.null`, which returns a `SoberSwag::Reporting::Output::Null`.
+  This type serializes out `null` in JSON.
+  This can only serialize the ruby value `nil`.
+- `SoberSwag::Reporting::Output.number`, returns a `SoberSwag::Reporting::Output::Number`.
+  This type serializes out numbers in JSON.
+  It can serialize out most ruby numeric types, including `Integer` and `Float`.
+- `SoberSwag::Reporting::Output.text`, which returns a `SoberSwag::Reporting::Output::Text`.
+  This serializes out a string type in the JSON.
+  It can serialize out ruby strings.
+
+### The Transforming Type
+
+For `SoberSwag::Reporting::Output`, there's a "fundamental" type that does *transformation*, called `via_map`.
+It lets you apply a ruby block before passing the input on to the serializer after it.
+It's most often used like this:
+
+```ruby
+screaming_output = SoberSwag::Reporting::Output.text.via_map { |old_text| old_text.upcase }
+screaming_output.call("what the heck")
+# => "WHAT THE HECK"
+```
+
+Note that this calls the block *before* passing to the next serializer.
+So:
+
+```ruby
+example = SoberSwag::Reporting::Output.text.via_map { |x| x.downcase }.via_map { |x| x + ", OK?" }
+example.call("WHAT THE HECK?")
+# => "what the heck, ok?"
+```
+
+This type winds up being extremely useful in a *lot* of places.
+For example, you can use it to provide extra information to a serializer:
+
+```ruby
+serializer = MyCoolOutput.via_map { |x| CoolStruct.new(record: x, metadata: metadata_from_elsewhere) }
+render json: serializer.list.call(my_record_relation)
+```
+
+### Composite Types
+
+The following "composite types," or types built from other types, are available:
+
+- `SoberSwag::Reporting::Output::List`, which seralizes out *lists* of values.
+  You can construct one in two ways:
+
+  ```ruby
+  SoberSwag::Reporting::Output::List.new(SoberSwag::Reporting::Output.text)
+  # or, via the instance method
+  SoberSwag::Reporting::Output.text.list
+  ```
+  This produces an output that can serialize to JSON arrays.
+  For example, either of these can produce:
+
+  ```json
+  ["foo", "bar"]
+  ```
+
+  This serialize will work with anything that responds to `#map`.
+
+- `SoberSwag::Reporting::Output::Dictionary`, which can be constructed via:
+  ```ruby
+  SoberSwag::Reporting::Output::Dictionary.of(SoberSwag::Reporting::Output.number)
+  ```
+
+  This type serializes out a key-value dictionary, IE, a JSON object.
+  So, the above can serialize:
+  ```ruby
+  { "foo": 10, "bar": 11 }
+  ```
+  This type will only serialize out ruby hashes.
+  It will, conveniently, convert symbol keys to strings for you.
+
+- `SoberSwag::Reporting::Output::Partitioned`, which represents the *choice* of two serializers.
+  It takes in a block to decide which serializer to use, a serializer to use if the block returns `true`, and a serializer to use if the block returns `false`.
+  That is, to serialize out *either* a string *or* a number, you might use:
+  ```ruby
+  SoberSwag::Reporting::Output::Partitioned.new(
+    proc { |x| x.is_a?(String) },
+    SoberSwag::Reporting::Output.text,
+    SoberSwag::Reporting::Output.number
+  )
+  ```
+- `SoberSwag::Reporting::Output::Viewed`, which lets you define a *view map* for an object.
+  This is mostly used as an implementation detail, but can be occasionally useful if you want to provide
+  a list of "views" with no common "base," like an output object might have. In this case, the "base"
+  view is more of a "default" rather than a "parent."
+
+### Validation Types
+
+OpenAPI v3 supports some *validations* on types, in addition to raw types.
+For example, you can specify in your documentation that a value will be within a *range* of values.
+These `SoberSwag::Reporting::Output` types provide that documentation - and perform those validations!
+
+- `SoberSwag::Reporting::Output::InRange` validates that a value will be within a certain *range* of values.
+  This is most useful with numbers.
+  For example:
+  ```ruby
+  SoberSwag::Reporting::Output.number.in_range(0..10)
+  ```
+- `SoberSwag::Reporting::Output::Pattern` validates that a value will match a certain *pattern.*
+  This is useful with strings:
+  ```ruby
+  SoberSwag::Reporting::Output::Pattern.new(SoberSwag::Reporting::Output.text, /foo|bar|baz|my-[0-5*/)
+  ```
+
+## `SoberSwag::Reporting::Input`
+
+This module is used for *parsers*, which take in some input and return a nicer type.
+
+### Basic Types
+
+These types are the "primitives" of `SoberSwag::Reporting::Input`, the most basic types:
+
+- `SoberSwag::Reporting::Input::Null` parses a JSON `null` value.
+  It will parse it to a ruby `nil`, naturally.
+  You probably want to construct one via `SoberSwag::Reporting::Input.null`.
+- `SoberSwag::Reporting::Input::Number` parses a JSON number.
+  It will parse to either a ruby `Integer` or a ruby `Float`, depending on the format (we use Ruby's internal format for this).
+  You probably want to construct one via `SoberSwag::Reporting::Input.number`.
+- `SoberSwag::Reporting::Input::Bool`, which parses a JSON bool (`true` or `false`).
+  This will parse to a ruby `true` or `false`.
+  You probably want to construct it with `SoberSwag::Reporting::Output.bool`.
+- `SoberSwag::Reporting::Input::Text`, which parses a JSON string (`"mike stoklassa"`, `"richard evans"`, or `"jay bauman"` for example).
+  This will parse to a ruby string.
+  You probably want to construct it with `SoberSwag::Reporting::Output.text`.
+
+### The Transforming Type
+
+Much like `via_map` for `SoberSwag::Reporting::Output`, there's a fundamental type that does *transformation*, called the `mapped`.
+This lets you do some transformation of input *after* others have ran.
+So:
+
+```ruby
+quiet = SoberSwag::Reporting::Input.text.mapped { |x| x.downcase }
+quiet.call("WHAT THE HECK")
+# => "what the heck"
+```
+
+Note that this composes as follows:
+
+```ruby
+example = SoberSwag::Reporting::Input.text.mapped { |x| x.downcase }.mapped { |x| x + ", OK?" }
+
+example.call("WHAT THE HECK")
+# => "what the heck, OK?"
+# As you can see, the *first* function applies first, then the *second*.
+```
+
+You might notice that this is the opposite behavior of of `SoberSwag::Reporting::Output::ViaMap`.
+This is because *serialization* is the *opposite* of *parsing*.
+Kinda neat, huh?
+
+### Composite Types
+
+These types work with *one or more* inputs to build up *another*.
+
+- `SoberSwag::Reporting::Input::List`, which lets you parse a JSON array.
+  IE:
+  ```ruby
+  SoberSwag::Reporting::Input::List.of(SoberSwag::Reporting::Input.number)
+  ```
+  Lets you parse a list of numbers.
+- `SoberSwag::Reporting::Input::Either`, which lets you parse one input, and if that fails, parse another.
+  This represents a *choice* of input types.
+  This is best used via:
+  ```ruby
+  SoberSwag::Reporting::Input.text | SoberSwag::Reporting::Input.number
+  # or
+  SoberSwag::Reporting::Input.text.or SoberSwag::Reporting::Input.number
+  ```
+  This is useful if you want to allow multiple input formats.
+- `SoberSwag::Reporting::Input::Dictionary`, which lets you parse a JSON dictionary with arbitrary keys.
+  For example, to parse this JSON (assuming you don't know the keys ahead of time):
+  ```json
+  {
+    "mike": 100,
+    "bob": 1000,
+    "joey": 12,
+    "yes": 1213
+  }
+  ```
+  You can use:
+  ```ruby
+  SoberSwag::Reporting::Input::Dictionary.of(SoberSwag::Reporting::Input.number)
+  ```
+
+  This will parse to a Ruby hash, with string keys.
+  If you want symbols, you can simply use `.mapped`:
+  ```ruby
+  SoberSwag::Reporting::Input::Dictionary.of(
+    SoberSwag::Reporting::Input.number
+  ).mapped { |hash| hash.transform_keys(&:to_sym) }
+  ```
+  Pretty cool, right?
+- `SoberSwag::Reporting::Input::Enum`, which lets you parse an *enum value*.
+  This input will validate that the given value is in the enum.
+  Note that this doesn't only work with strings!
+  You can use:
+
+  ```ruby
+  SoberSwag::Reporting::Input.number.enum(-1, 0, 1)
+  ```
+
+  And things will work fine.
+
+### Validating Types
+
+These types provide *validation* on an input.
+The validations provided match the specifications in swagger.
+
+- `SoberSwag::Reporting::Input::InRange`, which specifies that a value should be *within a range*.
+  You can use it like:
+
+  ```ruby
+  SoberSwag::Reporting::Input::InRange.new(
+    SoberSwag::Reporting::Input::Number,
+    1..100
+  )
+  ```
+- `SoberSwag::Reporting::Input::MultipleOf`, which specifies that a number is a *multiple of* some other number.
+  You can use it like this:
+  ```ruby
+  SoberSwag::Reporting::Input.number.multiple_of(2)
+  ```
+
+  Note that the `#multiple_of` method is only available on the `SoberSwag::Reporting::Input::Number` class.
+- `SoberSwag::Reporting::Input::Pattern`, which lets you check that an input *matches a regexp*.
+  You can use it like:
+
+  ```ruby
+  SoberSwag::Reporting::Input.text.with_pattern(/\A(R|r)ich (E|e)vans\z/)
+  ```
+
+  Note that the `with_pattern` method is only available on `SoberSwag::Reporting::Input::Text`
+
+#### Custom Validations
+
+You might have a scenario where you need to do a *custom validation* that is not in this list.
+In order to do this, you can use our old friend, `mapped`.
+If you return any instance of `SoberSwag::Reporting::Report::Base` from via-map, it will be treated as a *parse error*.
+This can be used for custom validations, like so:
+
+```ruby
+UuidInput = SoberSwag::Reporting::Input.text.format('custom-identifier').mapped do |inputted_string|
+  if inputted_string == 'special-value'
+    SoberSwag::Reporting::Report::Value.new(['was the string "special-value", which is reserved'])
+  else
+    inputted_string
+  end
+end
+```
+
+Please note that this functionality is intended to enable data *format* validation.
+**If you are making a call to a database or some API within a `mapped` block, you are doing something weird**.
+Sometimes you do need to do weird things, of course, but it is generally **not appropriate** to use input validation to ensure that ids exist or whatever - leave that up to your rails models!
+
+### Documentating Types
+
+These types allow you to add additional documentation.
+
+- `SoberSwag::Reporting::Input::Format`, which provides *format description*.
+  This lets you specify that a given input should have a given format.
+  Formats are just a string, so you can use custom formats:
+  ```ruby
+  SoberSwag::Reporting::Input.text.format('user-uuid')
+  ```
+
+  Note that adding a format *will not do any magic validation whatsoever*.
+  See the section on custom validations for how to do that.
+
+### Converting Types
+
+For convenience's sake, SoberSwag comes with a few built-in *converting inputs*.
+These convert JSON objects into some common types that you would want to use in ruby.
+
+- `SoberSwag::Reporting::Input::Converting::Bool`, which tries to coerce an input value to a boolean.
+  It will convert the following JSON values to `true`:
+
+  - The strings `"y"`, `"yes"`, `"true"`, `"t"`, or the all-caps variants of any
+  - The string `"1"`
+  - The number `1`
+  - a JSON `true`
+
+  And the following to false:
+
+  - The strings `"f"`, `"no"`, `"false"`, `"n"`, or any allcaps variant
+  - The number `0`
+  - An actual JSON `false`
+- `SoberSwag::Reporting::Input::Converting::Date`, which tries to parse a date string.
+  More specifically, it:
+  - First tries to parse a date with [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339).
+    It uses [`Date#rfc3339`](https://ruby-doc.org/stdlib-3.1.2/libdoc/date/rdoc/Date.html#method-c-rfc3339) to do this.
+  - Then tries to parse with [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601).
+    It uses [`Date#iso8601`](https://ruby-doc.org/stdlib-3.1.2/libdoc/date/rdoc/Date.html#method-c-iso8601) to do this.
+  - If both of the above fail, return a descriptive error (more specifically, the error specifies that the string was not an RFC 3339 date string or an ISO 8601 date string).
+- `SoberSwag::Reporting::Input::Converting::DateTime`, which works in much the same way.
+  More specifically, it...
+  - First tries to parse a timestamp with [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339).
+    It uses [`DateTime#rfc3339`](https://ruby-doc.org/stdlib-2.6.1/libdoc/date/rdoc/DateTime.html#method-c-rfc3339) to do this.
+  - Then tries to parse with [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601).
+    It uses [`DateTime#iso8601`](https://ruby-doc.org/stdlib-2.6.1/libdoc/date/rdoc/DateTime.html#method-c-iso8601) to do this.
+  - If both of the above fail, return a descriptive error (more specifically, the error specifies that the string was not an RFC 3339 date-time or an ISO 8601 date-time string).
+- `SoberSwag::Reporting::Input::Converting::Decimal`, which tries to parse a decimal number.
+  If a number is passed, it will convert that number to a `BigDecimal` via `#to_d`.
+  If a string is passed, it uses [`Kernel#BigDecimal`](https://ruby-doc.org/stdlib-2.6/libdoc/bigdecimal/rdoc/Kernel.html#method-i-BigDecimal) to try to parse a decimal from a string.
+  Note: you may wish to combine this with some sort of source-length check, to ensure people cannot force you to construct extremely large, memory-intense decimals.
+- `SoberSwag::Reporting::Input::Converting::Integer`, which tries to parse an integer number.
+  If a JSON number is passed, it uses `#to_i` to convert it to an integer.
+  If a string it passed, it uses [`Kernel#Integer`](https://ruby-doc.org/core-2.7.1/Kernel.html) to attempt to do the conversion, and reports an error if that fails.

data/example/Gemfile

@@ -8,7 +8,7 @@ gem 'actionpack', '>= 6.0.3.2'
 # Use sqlite3 as the database for Active Record
 gem 'sqlite3', '~> 1.4'
 # Use Puma as the app server
-gem 'puma', '~> 5.4'
+gem 'puma', '~> 5.6'
 # Build JSON APIs with ease. Read more: https://github.com/rails/jbuilder
 # gem 'jbuilder', '~> 2.7'
 # Use Active Model has_secure_password

data/example/Gemfile.lock

@@ -64,14 +64,14 @@ GEM
       minitest (~> 5.1)
       tzinfo (~> 1.1)
       zeitwerk (~> 2.2, >= 2.2.2)
-    bootsnap (1.9.3)
-      msgpack (~> 1.0)
+    bootsnap (1.11.1)
+      msgpack (~> 1.2)
     builder (3.2.4)
     byebug (11.1.3)
     coderay (1.1.3)
-    concurrent-ruby (1.1.9)
+    concurrent-ruby (1.1.10)
     crass (1.0.6)
-    diff-lcs (1.4.4)
+    diff-lcs (1.5.0)
     dry-configurable (0.13.0)
       concurrent-ruby (~> 1.0)
       dry-core (~> 0.6)
@@ -98,16 +98,16 @@ GEM
       dry-types (>= 0.8.1)
       rails (>= 3)
     erubi (1.10.0)
-    ffi (1.15.4)
+    ffi (1.15.5)
     globalid (1.0.0)
       activesupport (>= 5.0)
-    i18n (1.8.11)
+    i18n (1.10.0)
       concurrent-ruby (~> 1.0)
     ice_nine (0.11.2)
-    listen (3.7.0)
+    listen (3.7.1)
       rb-fsevent (~> 0.10, >= 0.10.3)
       rb-inotify (~> 0.9, >= 0.9.10)
-    loofah (2.12.0)
+    loofah (2.16.0)
       crass (~> 1.0.2)
       nokogiri (>= 1.5.9)
     mail (2.7.1)
@@ -115,17 +115,17 @@ GEM
     marcel (1.0.2)
     method_source (1.0.0)
     mini_mime (1.1.2)
-    mini_portile2 (2.6.1)
-    minitest (5.14.4)
-    msgpack (1.4.2)
+    mini_portile2 (2.8.0)
+    minitest (5.15.0)
+    msgpack (1.5.1)
     nio4r (2.5.8)
-    nokogiri (1.12.5)
-      mini_portile2 (~> 2.6.1)
+    nokogiri (1.13.6)
+      mini_portile2 (~> 2.8.0)
       racc (~> 1.4)
     pry (0.14.1)
       coderay (~> 1.1)
       method_source (~> 1.0)
-    puma (5.5.2)
+    puma (5.6.4)
       nio4r (~> 2.0)
     racc (1.6.0)
     rack (2.2.3)
@@ -158,18 +158,18 @@ GEM
       rake (>= 0.8.7)
       thor (>= 0.20.3, < 2.0)
     rake (13.0.6)
-    rb-fsevent (0.11.0)
+    rb-fsevent (0.11.1)
     rb-inotify (0.10.1)
       ffi (~> 1.0)
-    rspec-core (3.10.1)
-      rspec-support (~> 3.10.0)
-    rspec-expectations (3.10.1)
+    rspec-core (3.11.0)
+      rspec-support (~> 3.11.0)
+    rspec-expectations (3.11.0)
       diff-lcs (>= 1.2.0, < 2.0)
-      rspec-support (~> 3.10.0)
-    rspec-mocks (3.10.2)
+      rspec-support (~> 3.11.0)
+    rspec-mocks (3.11.1)
       diff-lcs (>= 1.2.0, < 2.0)
-      rspec-support (~> 3.10.0)
-    rspec-rails (5.0.2)
+      rspec-support (~> 3.11.0)
+    rspec-rails (5.1.2)
       actionpack (>= 5.2)
       activesupport (>= 5.2)
       railties (>= 5.2)
@@ -177,7 +177,7 @@ GEM
       rspec-expectations (~> 3.10)
       rspec-mocks (~> 3.10)
       rspec-support (~> 3.10)
-    rspec-support (3.10.3)
+    rspec-support (3.11.0)
     spring (2.1.1)
     spring-watcher-listen (2.0.1)
       listen (>= 2.7, < 4.0)
@@ -190,14 +190,14 @@ GEM
       activesupport (>= 5.2)
       sprockets (>= 3.0.0)
     sqlite3 (1.4.2)
-    thor (1.1.0)
+    thor (1.2.1)
     thread_safe (0.3.6)
     tzinfo (1.2.9)
       thread_safe (~> 0.1)
     websocket-driver (0.7.5)
       websocket-extensions (>= 0.1.0)
     websocket-extensions (0.1.5)
-    zeitwerk (2.5.1)
+    zeitwerk (2.5.4)
 
 PLATFORMS
   ruby
@@ -209,7 +209,7 @@ DEPENDENCIES
   dry-types-rails
   listen (>= 3.0.5, < 3.8)
   pry
-  puma (~> 5.4)
+  puma (~> 5.6)
   rails (~> 6.0.2, >= 6.0.2.2)
   rspec-rails
   sober_swag!

data/lib/sober_swag/input_object.rb

@@ -42,6 +42,7 @@ module SoberSwag
       #   @param type the attribute type
       def attribute(key, parent = SoberSwag::InputObject, &block)
         raise ArgumentError, "parent class #{parent} is not an input object type!" unless valid_field_def?(parent, block)
+        raise ArgumentError, "cannot mix reporting and non-reporting types at attribute #{key}" if parent.is_a?(SoberSwag::Reporting::Input::Interface)
 
         super(key, parent, &block)
       end

data/lib/sober_swag/output_object/field_syntax.rb

@@ -11,6 +11,8 @@ module SoberSwag
       # @param from [Symbol] method name to extract this field from, for convenience.
       # @param block [Proc] optional way to extract this field.
       def field(name, serializer, from: nil, &block)
+        raise ArgumentError, "do not mix reporting and non-reporting outputs (at key #{name})" if serializer.is_a?(SoberSwag::Reporting::Output::Interface)
+
         add_field!(Field.new(name, serializer, from: from, &block))
       end
 

data/lib/sober_swag/reporting/input/interface.rb

@@ -35,6 +35,8 @@ module SoberSwag
           List.new(self)
         end
 
+        alias array list
+
         ##
         # Constrained values: must be in range.
         # @return [InRange]

data/lib/sober_swag/reporting/input/list.rb

@@ -6,6 +6,12 @@ module SoberSwag
       #
       # Called List to avoid name conflicts.
       class List < Base
+        ##
+        # @see #new
+        def self.of(element)
+          initialize(element)
+        end
+
         ##
         # @param element [Base] the parser for elements
         def initialize(element)

data/lib/sober_swag/reporting/input/number.rb

@@ -10,6 +10,13 @@ module SoberSwag
           input
         end
 
+        ##
+        # @param other [Integer] number to specify this is a multiple of
+        # @return [SoberSwag::Reporting::Input::MultipleOf]
+        def multiple_of(other)
+          MultipleOf.new(self, other)
+        end
+
         def swagger_schema
           [{ type: 'number' }, {}]
         end

data/lib/sober_swag/reporting/input/struct.rb

@@ -76,6 +76,7 @@ module SoberSwag
           #
           def add_attribute!(name, input, required:, description: nil)
             raise ArgumentError, 'name must be a symbol' unless name.is_a?(Symbol)
+            raise ArgumentError, 'input type must be a SoberSwag::Reporting::Input::Interface' unless input.is_a?(Interface)
 
             define_attribute(name) # defines an instance method to access this attribute
 

data/lib/sober_swag/reporting/output/in_range.rb

@@ -0,0 +1,64 @@
+module SoberSwag
+  module Reporting
+    module Output
+      ##
+      # Specify that an output will be within a certain range.
+      # This gets translated to `minimum` and `maximum` keys in swagger.
+      class InRange < Base
+        def initialize(output, range)
+          @output = output
+          @range = range
+        end
+
+        ##
+        # @return [Interface]
+        attr_reader :output
+
+        ##
+        # @return [Range]
+        attr_reader :range
+
+        def call(value)
+          output.call(value)
+        end
+
+        def serialize_report(value)
+          rep = output.serialize_report(value)
+
+          return rep if rep.is_a?(Report::Base)
+
+          return Report::Value.new(['was not in minimum/maximum range']) unless range.member?(rep)
+
+          rep
+        end
+
+        def swagger_schema
+          schema, found = output.swagger_schema
+
+          merged =
+            if schema.key?(:$ref)
+              { allOf: [schema] }
+            else
+              schema
+            end.merge(maximum_portion).merge(minimum_portion)
+
+          [merged, found]
+        end
+
+        def maximum_portion
+          return {} unless range.end
+
+          res = { maximum: range.end }
+          res[:exclusiveMaximum] = true if range.exclude_end?
+          res
+        end
+
+        def minimum_portion
+          return {} unless range.begin
+
+          { minimum: range.begin }
+        end
+      end
+    end
+  end
+end

data/lib/sober_swag/reporting/output/interface.rb

@@ -40,10 +40,21 @@ module SoberSwag
           Referenced.new(self, name)
         end
 
+        ##
+        # @return [SoberSwag::Reporting::Output::InRange]
+        # Constrained values: must be within the given range.
+        def in_range(range)
+          raise ArgumentError, 'need a range' unless range.is_a?(Range)
+
+          InRange.new(self, range)
+        end
+
         def list
           List.new(self)
         end
 
+        alias array list
+
         ##
         # Partition this serializer into two potentials.
         # If the block given returns *false*, we will use `other` as the serializer.
@@ -76,10 +87,6 @@ module SoberSwag
           )
         end
 
-        def array
-          List.new(self)
-        end
-
         def described(description)
           Described.new(self, description)
         end

data/lib/sober_swag/reporting/output/struct.rb

@@ -20,6 +20,8 @@ module SoberSwag
           #
           #   You can access other methods from this method.
           def field(name, output, description: nil, &extract)
+            raise ArgumentError, bad_field_message(name, output) unless output.is_a?(Interface)
+
             define_field(name, extract)
 
             object_fields[name] = Object::Property.new(
@@ -158,22 +160,20 @@ module SoberSwag
           # @param name [Symbol] name of this view.
           # @yieldself [self] a block in which you can add more fields to the view.
           # @return [Class]
-          def define_view(name, &block) # rubocop:disable Metrics/MethodLength
-            raise ArgumentError, "duplicate view #{name}" if name == :base || views.include?(name)
-
-            classy_name = name.to_s.classify
+          def define_view(name, &block)
+            define_view_with_parent(name, self, block)
+          end
 
-            Class.new(self).tap do |c|
-              c.instance_eval(&block)
-              c.define_singleton_method(:define_view) do |*|
-                raise ArgumentError, 'no nesting views'
-              end
-              c.define_singleton_method(:identifier) do
-                [parent_struct.identifier, classy_name.gsub('::', '.')].join('.')
-              end
-              const_set(classy_name, c)
-              view_map[name] = c
-            end
+          ##
+          # Defines a view for this object, which "inherits" another view.
+          # @see #define_view for how views behave.
+          #
+          # @param name [Symbol] name of this view
+          # @param inherits [Symbol] name of the view this view inherits
+          # @yieldself [self] a block in which you can add more fields to this view
+          # @return [Class]
+          def define_inherited_view(name, inherits:, &block)
+            define_view_with_parent(name, view_class(inherits), block)
           end
 
           ##
@@ -199,6 +199,16 @@ module SoberSwag
             view_map.fetch(name).view(:base)
           end
 
+          ##
+          # Equivalent to .view, but returns the raw view class.
+          #
+          # @return [Class]
+          def view_class(name)
+            return self if name == :base
+
+            view_map.fetch(name)
+          end
+
           attr_accessor :parent_struct
 
           ##
@@ -226,6 +236,29 @@ module SoberSwag
 
           private
 
+          def bad_field_message(name, field_type)
+            [
+              "Output type used for field #{name.inspect} was",
+              "#{field_type.inspect}, which is not an instance of",
+              SoberSwag::Reporting::Output::Interface.name
+            ].join(' ')
+          end
+
+          def define_view_with_parent(name, parent, block)
+            raise ArgumentError, "duplicate view #{name}" if name == :base || views.include?(name)
+
+            classy_name = name.to_s.classify
+            us = self # grab this so its identifier doesn't get nested under whatever parent it inherits from, since its our view
+
+            Class.new(parent).tap do |c|
+              c.instance_eval(&block)
+              c.define_singleton_method(:define_view) { |*| raise ArgumentError, 'no nesting views' }
+              c.define_singleton_method(:identifier) { [us.identifier, classy_name.gsub('::', '.')].join('.') }
+              const_set(classy_name, c)
+              view_map[name] = c
+            end
+          end
+
           def identified_view_map
             view_map.transform_values(&:identified_without_base).merge(base: inherited_output)
           end

data/lib/sober_swag/reporting/output.rb

@@ -10,6 +10,7 @@ module SoberSwag
       autoload(:Defer, 'sober_swag/reporting/output/defer')
       autoload(:Described, 'sober_swag/reporting/output/described')
       autoload(:Dictionary, 'sober_swag/reporting/output/dictionary')
+      autoload(:InRange, 'sober_swag/reporting/output/in_range')
       autoload(:Interface, 'sober_swag/reporting/output/interface')
       autoload(:List, 'sober_swag/reporting/output/list')
       autoload(:MergeObjects, 'sober_swag/reporting/output/merge_objects')

data/lib/sober_swag/reporting/report/error.rb

@@ -8,6 +8,10 @@ module SoberSwag
           @report = report
         end
 
+        def message
+          "Reported errors: #{report.full_errors.join(', ')}"
+        end
+
         attr_reader :report
       end
     end

data/lib/sober_swag/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module SoberSwag
-  VERSION = '0.23.0'
+  VERSION = '0.25.0'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: sober_swag
 version: !ruby/object:Gem::Version
-  version: 0.23.0
+  version: 0.25.0
 platform: ruby
 authors:
 - Anthony Super
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2022-01-03 00:00:00.000000000 Z
+date: 2022-06-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -326,6 +326,7 @@ files:
 - lib/sober_swag/reporting/output/described.rb
 - lib/sober_swag/reporting/output/dictionary.rb
 - lib/sober_swag/reporting/output/enum.rb
+- lib/sober_swag/reporting/output/in_range.rb
 - lib/sober_swag/reporting/output/interface.rb
 - lib/sober_swag/reporting/output/list.rb
 - lib/sober_swag/reporting/output/merge_objects.rb