sober_swag 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f00dc3f047ad2bc40f12096ff56ebfd6ba3018cc05d0115ce400bc851cc382f9
-  data.tar.gz: 0f9819bf9bc3135b86fd2dde790e58477b0e3c0865a580987a6203a32a8eec34
+  metadata.gz: cdf3896754f6acf3bef2df51e947439be3822d3635eb924d6029ab3157b13bd9
+  data.tar.gz: 75846c0b78e4e8dc9fc550af50aeb2bb73f3c1200e8c50af6c07092d2dd8c277
 SHA512:
-  metadata.gz: e41afbd4771aca33e626c5bbad84cc5826ccf11c042878f9453a3cffb2d396b3f58e1d254c3fdf8cd5a847c079a697f68972e9e129f589af1e3b084208954775
-  data.tar.gz: 17b7771051bbde79bedcd1c4094f32cb612e24a5d9dfbe05b522bf086e55dbf43dae6ebf05d0c9cc447b3e8a8600918a83885fac1526ec598938b97f4ca5b1de
+  metadata.gz: ae7076a9dcabcf2a99b642f967782195d1680ff13b6fd251123abdec15ec2eab18435ec1897fe212a060779b1bdffb8061bcb4b2eb89884713230ca0c70ecc27
+  data.tar.gz: 5f3fb9ee3c31feb8ede072171e5f0f2f5108061d7f09c44e4f4d88d929c001519734fce64b4c261ea4d8e63d9aa1862fdf374cdddd00da2b58d9cf75fc367320

data/.github/config/rubocop_linter_action.yml

@@ -2,4 +2,3 @@ check_name: 'Rubocop Lint'
 versions:
   rubocop: 'latest'
   rubocop-rspec: 'latest'
-

data/.gitignore

@@ -10,5 +10,6 @@
 # rspec failure tracking
 .rspec_status
 .ruby-version
+Gemfile.lock
 
 *.gem

data/.rubocop.yml

@@ -3,7 +3,7 @@ Style/FrozenStringLiteralComment:
 Style/BlockDelimiters:
   EnforcedStyle: braces_for_chaining
 AllCops:
-  TargetRubyVersion: 2.7.1
+  TargetRubyVersion: 2.6.0
   Exclude:
     - 'bin/bundle'
     - 'example/bin/bundle'
@@ -31,6 +31,8 @@ Metrics/AbcSize:
 Style/Documentation:
   Exclude:
     - 'example/db/migrate/**/*'
+Metrics/PerceivedComplexity:
+  Enabled: false
 Layout/EmptyLinesAroundAttributeAccessor:
   Enabled: true
 Layout/SpaceAroundMethodCallOperator:

data/README.md

@@ -4,13 +4,11 @@
 ![Linters Status](https://github.com/SonderMindOrg/sober_swag/workflows/Linters/badge.svg?branch=master)
 
 SoberSwag is a combination of [Dry-Types](https://dry-rb.org/gems/dry-types/1.2/) and [Swagger](https://swagger.io/) that makes your Rails APIs more awesome.
-Other tools generate documenation from a DSL.
+Other tools generate documentation from a DSL.
 This generates documentation from *types*, which (conveniently) also lets you get supercharged strong-params-on-steroids.
 
 An introductory presentation is available [here](https://www.icloud.com/keynote/0bxP3Dn8ETNO0lpsSQSVfEL6Q#SoberSwagPresentation).
 
-This gem uses pattern matching, and is thus only compatible with Ruby 2.7 or later.
-
 ## Types for a fully-automated API
 
 SoberSwag lets you type your API using describe blocks.
@@ -18,22 +16,22 @@ In any controller that includes `SoberSwag::Controller`, you get access to the s
 This lets you type your API endpoint:
 
 ```ruby
-  class PeopleController < ApplicationController
-    include SoberSwag::Controller
-    define :patch, :update, '/people/{id}' do
-      query_params do
-        attribute? :include_extra_info, Types::Params::Bool
-      end
-      request_body do
-        attribute? :name, Types::Params::String
-        attribute? :age, Types::Params::Integer
-      end
-      path_params { attribute :id, Types::Params::Integer }
+class PeopleController < ApplicationController
+  include SoberSwag::Controller
+  define :patch, :update, '/people/{id}' do
+    query_params do
+      attribute? :include_extra_info, Types::Params::Bool
+    end
+    request_body do
+      attribute? :name, Types::Params::String
+      attribute? :age, Types::Params::Integer
     end
+    path_params { attribute :id, Types::Params::Integer }
   end
+end
 ```
 
-We can now us this information to generate swagger documentation, available at the `swagger` action on this controller.
+We can now use this information to generate swagger documentation, available at the `swagger` action on this controller.
 More than that, we can use this information *inside* our controller methods:
 
 ```ruby
@@ -87,27 +85,75 @@ end
 
 Support for easily typing "render the activerecord errors for me please" is (unfortunately) under development.
 
-### SoberSwag Structs
+### SoberSwag Input Objects
 
 Input parameters (including path, query, and request body) are typed using [dry-struct](https://dry-rb.org/gems/dry-struct/1.0/).
-You don't have to do them inline: you can define them in another file, like so:
+You don't have to do them inline. You can define them in another file, like so:
 
 ```ruby
-User = SoberSwag.struct do
+User = SoberSwag.input_object do
   attribute :name, SoberSwag::Types::String
   # use ? if attributes are not required
   attribute? :favorite_movie, SoberSwag::Types::String
   # use .optional if attributes may be null
-  attribute :age, SoberSwag::Types::Params::::Integer.optional
+  attribute :age, SoberSwag::Types::Params::Integer.optional
+end
+```
+
+Then, in your controller, just do:
+
+```ruby
+class PeopleController < ApplicationController
+  include SoberSwag::Controller
+
+  define :path, :update, '/people/{id}' do
+    request_body(User)
+    path_params { attribute :id, Types::Params::Integer }
+    response(:ok, 'the updated person', PersonOutputObject)
+  end
+  def update
+    # same as above!
+  end
 end
 ```
 
 Under the hood, this literally just generates a subclass of `Dry::Struct`.
 We use the DSL-like method just to make working with Rails' reloading less annoying.
 
+#### Adding additional documentation
+
+You can use the `.meta` attribute on a type to add additional documentation.
+Some keys are considered "well-known" and will be present on the swagger output.
+For example:
+
+
+```ruby
+User = SoberSwag.input_object do
+  attribute? :name, SoberSwag::Types::String.meta(description: <<~MARKDOWN, deprecated: true)
+    The given name of the students, with strings encoded as escaped-ASCII.
+    This is used by an internal Cobol microservice from 1968.
+    Please use unicode_name instead unless you are that microservice.
+  MARKDOWN
+  attribute? :unicode_name, SoberSwag::Types::String
+end
+```
+
+This will output the swagger you expect, with a description and a deprecated flag.
+
+#### Adding Default Values
+
+Sometimes it makes sense to specify a default value.
+Don't worry, we've got you covered:
+
+```ruby
+QueryInput = SoberSwag.input_object do
+  attribute :allow_first, SoberSwag::Types::Params::Bool.default(false) # smartly alters type-definition to establish that passing this is not required.
+end
+```
+
 ## Special Thanks
 
-This gem is a mismatch of ideas from various sources.
+This gem is a mishmash of ideas from various sources.
 The biggest thanks is owed to the [dry-rb](https://github.com/dry-rb) project, upon which the typing of SoberSwag is based.
 On an API design level, much is owed to [blueprinter](https://github.com/procore/blueprinter) for the serializers.
 The idea of a strongly-typed API came from the Haskell framework [servant](https://www.servant.dev/).

data/bin/console

@@ -1,4 +1,4 @@
-#!/usr/bin/env ruby -W:no-experimental
+#!/usr/bin/env ruby
 # frozen_string_literal: true
 
 require 'bundler/setup'

data/docs/serializers.md

@@ -4,11 +4,11 @@ Serializers are a way to transform from one type to another.
 For example, you might want to change an ActiveRecord object to a JSON struct.
 You might also want to change an internal date-interval into a two-element array of dates, or some custom text format.
 You can do all of these things with SoberSwag serializers.
-Furthermore, Serializers document the *type* that they serialize, so you can use it to degenerate documentation.
+Furthermore, Serializers document the *type* that they serialize, so you can use it to generate documentation.
 
 ## The Basics
 
-All serializers are inherted from [`SoberSwag::Serializer::Base`](../lib/sober_swag/serializer/base.rb).
+All serializers are inherited from [`SoberSwag::Serializer::Base`](../lib/sober_swag/serializer/base.rb).
 This is an abstract class that implements several methods, most of which will be documented later.
 The two that are most interesting, however, are `#type` and `#serialize`.
 
@@ -55,12 +55,12 @@ In the future, we might add some "debug mode" sorta thing that will do type-chec
 
 ### Mapped
 
-Sometimes, you can create a serilaizer via a *proc*.
+Sometimes, you can create a serializer via a *proc*.
 For example, let's say that I want a serializer that takes a `Date` and returns a string.
 I can do this:
 
 ```ruby
-date_string = SoberSwag::Serializer.Primitive(:String).via_map { |d| d.to_s }
+date_string = SoberSwag::Serializer.primitive(:String).via_map { |d| d.to_s }
 ```
 
 This is implemented via [`SoberSwag::Serializer::Mapped`](../lib/sober_swag/serializer/mapped.rb).
@@ -87,7 +87,7 @@ my_serializer.optional.serialize(nil) # => nil
 # ^ nils become nil
 ```
 
-This properly changes the `type` to be a nillable type, as well.
+This properly changes the `type` to be a nilable type, as well.
 
 ### Array
 
@@ -121,9 +121,9 @@ Let's define an output object:
 
 ```ruby
 StudentOutputObject = SoberSwag::OutputObject.define do
-  field :first_name, Primitive(:String)
-  field :last_name, Primitive(:String)
-  field :recent_grades, Primitive(:Integer).array do |student|
+  field :first_name, primitive(:String)
+  field :last_name, primitive(:String)
+  field :recent_grades, primitive(:Integer).array do |student|
     student.graded_assignments.limit(100).pluck(:grade)
   end
 end
@@ -143,10 +143,10 @@ Let's take a look at their use:
 
 ```ruby
 StudentOutputObject = SoberSwag::OutputObject.define do
-  field :first_name, Primitive(:String)
-  field :last_name, Primitive(:String)
+  field :first_name, primitive(:String)
+  field :last_name, primitive(:String)
   view :detail do
-    field :recent_grades, Primitive(:Integer).array do |student|
+    field :recent_grades, primitive(:Integer).array do |student|
       student.graded_assignments.limit(100).pluck(:grade)
     end
   end
@@ -189,7 +189,7 @@ StudentOutputObject = SoberSwag::OutputObject.define do
 end
 ```
 
-This can cause a circular dependecy.
+This can cause a circular dependency.
 To break this, you can use a lambda:
 
 ```ruby
@@ -200,4 +200,4 @@ StudentOutputObject = SoberSwag::OutputObject.define do
 end
 ```
 
-For clarity (and to prevent infinitely-looping serializers on accident, we reccomend you *always* use an explicit view for dependent output objects.
+For clarity (and to prevent infinitely-looping serializers on accident, we recommend you *always* use an explicit view for dependent output objects.

data/example/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: ..
   specs:
-    sober_swag (0.4.0)
+    sober_swag (0.5.0)
       activesupport
       dry-struct (~> 1.0)
       dry-types (~> 1.2)

data/example/app/controllers/people_controller.rb

@@ -61,16 +61,18 @@ class PeopleController < ApplicationController
 
   define :get, :index, '/people/' do
     query_params do
-      attribute? :first_name, Types::String
-      attribute? :last_name, Types::String
-      attribute? :view, Types::String.enum('base', 'detail')
+      attribute? :filters do
+        attribute? :first_name, Types::String
+        attribute? :last_name, Types::String
+      end
+      attribute :view, Types::String.default('base'.freeze).enum('base', 'detail')
     end
     response(:ok, 'all the people', PersonOutputObject.array)
   end
   def index
     @people = Person.all
-    @people = @people.where('UPPER(first_name) LIKE UPPER(?)', "%#{parsed_query.first_name}%") if parsed_query.first_name
-    @people = @people.where('UPPER(last_name) LIKE UPPER(?)', "%#{parsed_query.last_name}%") if parsed_query.last_name
+    @people = @people.where('UPPER(first_name) LIKE UPPER(?)', "%#{parsed_query.filters.first_name}%") if parsed_query.filters&.first_name
+    @people = @people.where('UPPER(last_name) LIKE UPPER(?)', "%#{parsed_query.filters.last_name}%") if parsed_query.filters&.last_name
     respond!(:ok, @people.includes(:posts), serializer_opts: { view: parsed_query.view })
   end
 

data/example/app/controllers/posts_controller.rb

@@ -39,12 +39,20 @@ class PostsController < ApplicationController
   define :get, :index, '/posts/' do
     query_params do
       attribute? :view, ViewTypes
+      attribute :include_first, SoberSwag::Types::Params::Bool.default(false).meta(description: <<~MARKDOWN)
+        For historical reasons the first-ever post is the entire text of *Finnegan's Wake.*
+        Unfortunately, our contractors wound up depending on this quirk to complete dark arcane ceremonies,
+        so we can't remove it. Thus, by default, we don't include the first post unless you explicitly ask us to
+        (maybe you feel like some classic literature?).
+      MARKDOWN
     end
     response(:ok, 'all the posts', PostOutputObject.array)
   end
   def index
     @posts = Post.all
 
+    @posts = @posts.where('id > 1') unless parsed_query.include_first
+
     respond!(:ok, @posts.includes(:person), serializer_opts: { view: parsed_query.view })
   end
 

data/example/spec/requests/people/index_spec.rb

@@ -35,13 +35,13 @@ RSpec.describe 'Index action for people' do
     end
 
     context 'with a good first-name search' do
-      let(:request) { get '/people', params: { first_name: 'A' } }
+      let(:request) { get '/people', params: { filters: { first_name: 'A' } } }
 
       it_behaves_like 'a request with the person'
     end
 
     context 'with a good last-name search' do
-      let(:request) { get '/people', params: { last_name: 'G' } }
+      let(:request) { get '/people', params: { filters: { last_name: 'G' } } }
 
       it_behaves_like 'a request with the person'
     end

data/lib/sober_swag/compiler/type.rb

@@ -73,13 +73,16 @@ module SoberSwag
       end
 
       def path_schema
-        path_schema_stub.map { |e| e.merge(in: :path) }
+        path_schema_stub.map do |e|
+          ensure_uncomplicated(e[:name], e[:schema])
+          e.merge(in: :path)
+        end
       rescue TooComplicatedError => e
         raise TooComplicatedForPathError, e.message
       end
 
       def query_schema
-        path_schema_stub.map { |e| e.merge(in: :query) }
+        path_schema_stub.map { |e| e.merge(in: :query, style: :deepObject, explode: true) }
       rescue TooComplicatedError => e
         raise TooComplicatedForQueryError, e.message
       end
@@ -175,7 +178,7 @@ module SoberSwag
         end
       end
 
-      def to_object_schema(object) # rubocop:disable Metrics/MethodLength, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+      def to_object_schema(object) # rubocop:disable Metrics/MethodLength, Metrics/CyclomaticComplexity
         case object
         when Nodes::List
           {
@@ -239,13 +242,10 @@ module SoberSwag
       def path_schema_stub
         @path_schema_stub ||=
           object_schema[:properties].map do |k, v|
-            ensure_uncomplicated(k, v)
+            # ensure_uncomplicated(k, v)
             {
               name: k,
               schema: v.reject { |key, _| %i[required nullable].include?(key) },
-              # rubocop:disable Style/DoubleNegation
-              allowEmptyValue: !object_schema[:required].include?(k) || !!v[:nullable], # if it's required, no empties, but if *nullabe*, empties are okay
-              # rubocop:enable Style/DoubleNegation
               required: object_schema[:required].include?(k) || false
             }
           end

data/lib/sober_swag/output_object/field_syntax.rb

@@ -10,7 +10,7 @@ module SoberSwag
       ##
       # Given a symbol to this, we will use a primitive name
       def primitive(name)
-        SoberSwag::Serializer.Primitive(SoberSwag::Types.const_get(name))
+        SoberSwag::Serializer.primitive(SoberSwag::Types.const_get(name))
       end
     end
   end

data/lib/sober_swag/parser.rb

@@ -10,6 +10,9 @@ module SoberSwag
 
     def to_syntax # rubocop:disable Metrics/MethodLength, Metrics/CyclomaticComplexity
       case @node
+      when Dry::Types::Default
+        # we handle this elsewhere, so
+        bind(Parser.new(@node.type))
       when Dry::Types::Array::Member
         Nodes::List.new(bind(Parser.new(@node.member)))
       when Dry::Types::Enum
@@ -21,7 +24,7 @@ module SoberSwag
       when Dry::Types::Schema::Key
         Nodes::Attribute.new(
           @node.name,
-          @node.required?,
+          @node.required? && !@node.type.default?,
           bind(Parser.new(@node.type))
         )
       when Dry::Types::Sum

data/lib/sober_swag/serializer.rb

@@ -18,7 +18,7 @@ module SoberSwag
       # in values raw.
       #
       # @param contained {Class} Dry::Type to use
-      def Primitive(contained) # rubocop:disable Naming/MethodName
+      def primitive(contained)
         SoberSwag::Serializer::Primitive.new(contained)
       end
     end

data/lib/sober_swag/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: sober_swag
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.6.0
 platform: ruby
 authors:
 - Anthony Super
@@ -166,7 +166,6 @@ files:
 - ".ruby-version"
 - ".travis.yml"
 - Gemfile
-- Gemfile.lock
 - LICENSE.txt
 - README.md
 - Rakefile

data/Gemfile.lock

@@ -1,116 +0,0 @@
-PATH
-  remote: .
-  specs:
-    sober_swag (0.3.0)
-      activesupport
-      dry-struct (~> 1.0)
-      dry-types (~> 1.2)
-
-GEM
-  remote: https://rubygems.org/
-  specs:
-    activesupport (6.0.3.2)
-      concurrent-ruby (~> 1.0, >= 1.0.2)
-      i18n (>= 0.7, < 2)
-      minitest (~> 5.1)
-      tzinfo (~> 1.1)
-      zeitwerk (~> 2.2, >= 2.2.2)
-    ast (2.4.1)
-    coderay (1.1.2)
-    concurrent-ruby (1.1.6)
-    diff-lcs (1.4.4)
-    docile (1.3.2)
-    dry-configurable (0.11.6)
-      concurrent-ruby (~> 1.0)
-      dry-core (~> 0.4, >= 0.4.7)
-      dry-equalizer (~> 0.2)
-    dry-container (0.7.2)
-      concurrent-ruby (~> 1.0)
-      dry-configurable (~> 0.1, >= 0.1.3)
-    dry-core (0.4.9)
-      concurrent-ruby (~> 1.0)
-    dry-equalizer (0.3.0)
-    dry-inflector (0.2.0)
-    dry-logic (1.0.6)
-      concurrent-ruby (~> 1.0)
-      dry-core (~> 0.2)
-      dry-equalizer (~> 0.2)
-    dry-struct (1.3.0)
-      dry-core (~> 0.4, >= 0.4.4)
-      dry-equalizer (~> 0.3)
-      dry-types (~> 1.3)
-      ice_nine (~> 0.11)
-    dry-types (1.4.0)
-      concurrent-ruby (~> 1.0)
-      dry-container (~> 0.3)
-      dry-core (~> 0.4, >= 0.4.4)
-      dry-equalizer (~> 0.3)
-      dry-inflector (~> 0.1, >= 0.1.2)
-      dry-logic (~> 1.0, >= 1.0.2)
-    i18n (1.8.3)
-      concurrent-ruby (~> 1.0)
-    ice_nine (0.11.2)
-    method_source (0.9.2)
-    minitest (5.14.1)
-    parallel (1.19.2)
-    parser (2.7.1.4)
-      ast (~> 2.4.1)
-    pry (0.12.2)
-      coderay (~> 1.1.0)
-      method_source (~> 0.9.0)
-    rainbow (3.0.0)
-    rake (13.0.1)
-    regexp_parser (1.7.1)
-    rexml (3.2.4)
-    rspec (3.9.0)
-      rspec-core (~> 3.9.0)
-      rspec-expectations (~> 3.9.0)
-      rspec-mocks (~> 3.9.0)
-    rspec-core (3.9.2)
-      rspec-support (~> 3.9.3)
-    rspec-expectations (3.9.2)
-      diff-lcs (>= 1.2.0, < 2.0)
-      rspec-support (~> 3.9.0)
-    rspec-mocks (3.9.1)
-      diff-lcs (>= 1.2.0, < 2.0)
-      rspec-support (~> 3.9.0)
-    rspec-support (3.9.3)
-    rubocop (0.88.0)
-      parallel (~> 1.10)
-      parser (>= 2.7.1.1)
-      rainbow (>= 2.2.2, < 4.0)
-      regexp_parser (>= 1.7)
-      rexml
-      rubocop-ast (>= 0.1.0, < 1.0)
-      ruby-progressbar (~> 1.7)
-      unicode-display_width (>= 1.4.0, < 2.0)
-    rubocop-ast (0.1.0)
-      parser (>= 2.7.0.1)
-    rubocop-rspec (1.42.0)
-      rubocop (>= 0.87.0)
-    ruby-progressbar (1.10.1)
-    simplecov (0.18.5)
-      docile (~> 1.1)
-      simplecov-html (~> 0.11)
-    simplecov-html (0.12.2)
-    thread_safe (0.3.6)
-    tzinfo (1.2.7)
-      thread_safe (~> 0.1)
-    unicode-display_width (1.7.0)
-    zeitwerk (2.4.0)
-
-PLATFORMS
-  ruby
-
-DEPENDENCIES
-  bundler (~> 2.0)
-  pry
-  rake (~> 13.0)
-  rspec (~> 3.0)
-  rubocop
-  rubocop-rspec
-  simplecov
-  sober_swag!
-
-BUNDLED WITH
-   2.1.4