sober_swag 0.1.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e58f142c7c7e5716d0d023844846ffcac306ff45f6ab84650cdf33003898ff83
-  data.tar.gz: 33e35fb1910ebe36f1618b2091e0cfb7762dbadbebaba046c8a67d3f58038e24
+  metadata.gz: cdf3896754f6acf3bef2df51e947439be3822d3635eb924d6029ab3157b13bd9
+  data.tar.gz: 75846c0b78e4e8dc9fc550af50aeb2bb73f3c1200e8c50af6c07092d2dd8c277
 SHA512:
-  metadata.gz: 747f4d9f9c0750de1a8109fb443bbe21df72929f74f447ce1473d676b2dcbc952c52dcc7731c6cd097d6f06452220ee808b883d4529da458b89baa2dde84ee76
-  data.tar.gz: 839284d0a57c363348e486320256c3f4d097b4c193eab3914416037a178a4a32e7b07e236e72b77376a68fce9715ffe62898a2b8ef7659fb9f2ccbf3a7b01378
+  metadata.gz: ae7076a9dcabcf2a99b642f967782195d1680ff13b6fd251123abdec15ec2eab18435ec1897fe212a060779b1bdffb8061bcb4b2eb89884713230ca0c70ecc27
+  data.tar.gz: 5f3fb9ee3c31feb8ede072171e5f0f2f5108061d7f09c44e4f4d88d929c001519734fce64b4c261ea4d8e63d9aa1862fdf374cdddd00da2b58d9cf75fc367320

data/.github/config/rubocop_linter_action.yml

@@ -0,0 +1,4 @@
+check_name: 'Rubocop Lint'
+versions:
+  rubocop: 'latest'
+  rubocop-rspec: 'latest'

data/.github/workflows/lint.yml

@@ -0,0 +1,15 @@
+name: Linters
+
+on: [push]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v1
+    - name: Rubocop Linter
+      uses: andrewmcodes/rubocop-linter-action@v3.0.0
+      with:
+        action_config_path: '.github/config/rubocop_linter_action.yml' # Note: this is the default location
+      env:
+        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

data/.github/workflows/ruby.yml

@@ -17,6 +17,9 @@ jobs:
   test:
 
     runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        ruby: [ '2.6', '2.7' ]
 
     steps:
     - uses: actions/checkout@v2
@@ -26,8 +29,36 @@ jobs:
     # uses: ruby/setup-ruby@v1
       uses: ruby/setup-ruby@ec106b438a1ff6ff109590de34ddc62c540232e0
       with:
-        ruby-version: 2.7
+        ruby-version:  ${{ matrix.ruby }}
+    - uses: actions/cache@v2
+      with:
+        path: vendor/bundle
+        key: ${{ runner.os }}-${{ matrix.ruby }}-gem-deps-${{ hashFiles('**/Gemfile.lock') }}
+        restore-keys: |
+          ${{ runner.os }}-${{ matrix.ruby }}-gem-deps-
     - name: Install dependencies
-      run: bundle install
+      run: |
+        bundle config path vendor/bundle
+        bundle install
     - name: Run tests
+      run: COVERAGE=1 bundle exec rake
+    - name: Upload Coverage
+      uses: actions/upload-artifact@master
+      if: always()
+      with:
+        name: coverage-report
+        path: coverage
+    - uses: actions/cache@v2
+      with:
+        path: example/vendor/bundle
+        key: ${{ runner.os }}-${{ matrix.ruby }}-example-deps-${{ hashFiles('example/**/Gemfile.lock') }}
+        restore-keys: |
+          ${{ runner.os }}-${{ matrix.ruby }}-example-deps-
+    - name: Install example dependencies for example
+      working-directory: example
+      run: |
+        bundle config path vendor/bundle
+        bundle install
+    - name: Run specs for example
+      working-directory: example
       run: bundle exec rake

data/.gitignore

@@ -9,3 +9,7 @@
 
 # rspec failure tracking
 .rspec_status
+.ruby-version
+Gemfile.lock
+
+*.gem

data/.rubocop.yml

@@ -3,5 +3,79 @@ Style/FrozenStringLiteralComment:
 Style/BlockDelimiters:
   EnforcedStyle: braces_for_chaining
 AllCops:
-  TargetRubyVersion: 2.7.0
+  TargetRubyVersion: 2.6.0
+  Exclude:
+    - 'bin/bundle'
+    - 'example/bin/bundle'
+
+Layout/LineLength:
+  Max: 160
 require: rubocop-rspec
+RSpec/NamedSubject:
+  Enabled: false
+RSpec/DescribeClass:
+  Enabled: false
+Metrics/BlockLength:
+  Exclude:
+    - 'spec/**/*.rb'
+    - 'sober_swag.gemspec'
+    - 'example/spec/**/*.rb'
+RSpec/ImplicitBlockExpectation:
+  Enabled: false
+RSpec/ImplicitExpect:
+  EnforcedStyle: should
+Style/MultilineBlockChain:
+  Enabled: false
+Metrics/AbcSize:
+  Enabled: false
+Style/Documentation:
+  Exclude:
+    - 'example/db/migrate/**/*'
+Metrics/PerceivedComplexity:
+  Enabled: false
+Layout/EmptyLinesAroundAttributeAccessor:
+  Enabled: true
+Layout/SpaceAroundMethodCallOperator:
+  Enabled: true
+Lint/DeprecatedOpenSSLConstant:
+  Enabled: true
+Lint/DuplicateElsifCondition:
+  Enabled: true
+Lint/MixedRegexpCaptureTypes:
+  Enabled: true
+Lint/RaiseException:
+  Enabled: true
+Lint/StructNewOverride:
+  Enabled: true
+Style/AccessorGrouping:
+  Enabled: true
+Style/ArrayCoercion:
+  Enabled: true
+Style/BisectedAttrAccessor:
+  Enabled: true
+Style/CaseLikeIf:
+  Enabled: true
+Style/ExponentialNotation:
+  Enabled: true
+Style/HashAsLastArrayItem:
+  Enabled: true
+Style/HashEachMethods:
+  Enabled: true
+Style/HashLikeCase:
+  Enabled: true
+Style/HashTransformKeys:
+  Enabled: true
+Style/HashTransformValues:
+  Enabled: true
+Style/RedundantAssignment:
+  Enabled: true
+Style/RedundantFetchBlock:
+  Enabled: true
+Style/RedundantFileExtensionInRequire:
+  Enabled: true
+Style/RedundantRegexpCharacterClass:
+  Enabled: true
+Style/RedundantRegexpEscape:
+  Enabled: true
+Style/SlicingWithRange:
+  Enabled: true

data/.ruby-version

@@ -1 +1 @@
-2.7.0
+2.6.5

data/README.md

@@ -1,7 +1,160 @@
 # SoberSwag
 
 ![Ruby Test Status](https://github.com/SonderMindOrg/sober_swag/workflows/Ruby/badge.svg?branch=master)
+![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).
+
+## Types for a fully-automated API
+
+SoberSwag lets you type your API using describe blocks.
+In any controller that includes `SoberSwag::Controller`, you get access to the super-cool DSL method `define`.
+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 }
+  end
+end
+```
+
+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
+def update
+  @person = Person.find(parsed_path.id)
+  @person.update!(parsed_body.to_h)
+end
+```
+
+No need for `params.require` or anything like that.
+You define the type of parameters you accept, and we reject anything that doesn't fit.
+
+### Typed Responses
+
+Want to go further and type your responses too?
+Use SoberSwag output objects, a serializer library heavily inspired by [Blueprinter](https://github.com/procore/blueprinter)
+
+```ruby
+PersonOutputObject = SoberSwag::OutputObject.define do
+  field :id, primitive(:Integer)
+  field :name, primitive(:String).optional
+  field :is_registered, primitive(:Bool) do |person|
+    person.registered?
+  end
+end
+```
+
+Now, in your `define` block, you can tell us that this is the *type* of your response:
+
+```ruby
+class PeopleController < ApplicationController
+  include SoberSwag::Controller
+  define :patch, :update, '/people/{id}' do
+    request_body do
+      attribute? :name, Types::Params::String
+      attribute? :age, Types::Params::Integer
+    end
+    path_params { attribute :id, Types::Params::Integer }
+    response(:ok, 'the updated person', PersonOutputObject)
+  end
+  def update
+    person = Person.find(parsed_path.id)
+    if person.update(parsed_body.to_h)
+      respond!(:ok, person)
+    else
+      render json: person.errors
+    end
+  end
+end
+```
+
+Support for easily typing "render the activerecord errors for me please" is (unfortunately) under development.
+
+### 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:
+
+```ruby
+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
+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 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/).
+Generating the swagger documenation happens via the use of a catamorphism, which I believe I first really understood thanks to [this medium article by Jared Tobin](https://medium.com/@jaredtobin/practical-recursion-schemes-c10648ec1c29).

data/bin/console

@@ -1,9 +1,8 @@
-#!/usr/bin/env ruby -W:no-experimental
+#!/usr/bin/env ruby
 # frozen_string_literal: true
 
 require 'bundler/setup'
 require 'sober_swag'
-require 'dry-struct'
 
 # You can add fixtures and/or initialization code here to make experimenting
 # with your gem easier. You can also use a different console, if you like.
@@ -11,28 +10,30 @@ module Types
   include Dry.Types()
 end
 
-class Bio < Dry::Struct
-  attribute :name, Types::String
+Bio = SoberSwag.input_object do
+  attribute :name, primitive(:String).meta(description: 'A very basic bio name')
 end
 
-class Person < Dry::Struct
-  attribute :name, Types::String
-  attribute :age, Types::Integer.constrained(gt: 0).optional | Types::String.optional
+Person = SoberSwag.input_object do
+  attribute :name, primitive(:String).meta(description: 'The full name description')
+  attribute :age, param(:Integer).constrained(gt: 0).optional.meta(description: 'My cool age')
   attribute? :mood, Types::String
-  attribute :bio, Bio
-
-  attribute :foo do
-    attribute :bar, Types::String
-    attribute :baz, Types::String.optional
-  end
 end
 
-class PersonSearch < Dry::Struct
+##
+# Demonstration of subclass-style.
+class PersonSearch < SoberSwag::InputObject
   attribute? :name, Types::String
   attribute? :age, Types::Integer
 end
 
+##
+# Demonstration of subclass-style *and* recursion in structs.
+class LinkedList < SoberSwag::InputObject
+  attribute :value, Types::String
+  attribute? :next, LinkedList
+end
 
 # (If you use this, don't forget to add pry to your Gemfile!)
-require "pry"
+require 'pry'
 Pry.start

data/docs/serializers.md

@@ -0,0 +1,203 @@
+# Serializers
+
+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 generate documentation.
+
+## The Basics
+
+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`.
+
+The first, `#type`, returns a SoberSwag-compatible type definition.
+This might be an instance of `SoberSwag::Struct`, or something else.
+You'll never need to implement this yourself, but you should note that we generally do not *enforce* these types *at serialization time*.
+This might change in the future, likely under a debug flag.
+
+The second, `#serialize`, does the actual work of serialization.
+It takes *two arguments*.
+The first is the argument that we will transform into the output type.
+The second is *always* optional, and is a *hash of options* to use to customize serialization.
+For example, you might have a serializer that can return a date in two formats, depending on a boolean flag.
+In this case, it might be used as:
+
+```ruby
+serializer.new(my_record, { format: :newstyle })
+```
+
+However, since it is *always* optional, you can also do:
+
+```ruby
+serilaizer.new(my_record)
+```
+
+And it *should* pick some default format.
+
+### Primitives
+
+Primitive serializers, or "identity serializers," are serializers that do nothing.
+They are implemented as [`SoberSwag::Serializer::Primitive`](../lib/sober_swag/serializer/primitive.rb), or as the `#primitive` method on a `OutputObject`.
+Since they don't do anything, they can be considered the most "basic" serializer.
+
+These serializers *do not* check types.
+That is, the following code will not throw an error:
+
+```ruby
+serializer = SoberSwag::Serializer::Primitive.new(SoberSwag::Types::String)
+serializer.serialize(10) # => 10
+```
+
+Thus, care should be used when working with these serializers.
+In the future, we might add some "debug mode" sorta thing that will do type-checking and throw errors, however, the cost of doing so in production is probably not worth it.
+
+### Mapped
+
+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 }
+```
+
+This is implemented via [`SoberSwag::Serializer::Mapped`](../lib/sober_swag/serializer/mapped.rb).
+Basically, it uses your given proc to do serialization.
+
+Once again, this does not do type-checking.
+In the future, we might add a debug mode.
+
+### Optional
+
+Oftentimes, we want to give a serializer the ability to serialize `nil` values.
+This is often useful in serializing fields.
+
+It turns out that it's pretty easy to make a serializer that can serialize `nil` values: just propogate nils.
+For example, let's say I have the following code:
+
+```ruby
+Foo = Struct.new(:bar, :baz)
+my_serializer.serialize(Foo.new(10, 11)) # => { bar: 10, baz: 11 }
+# ^ my_serializer is defined elsewhere
+my_serializer.optional.serialize(Foo.new(10, 11)) # => { bar: 10, baz: 11 }
+# ^ can serialize the type from before
+my_serializer.optional.serialize(nil) # => nil
+# ^ nils become nil
+```
+
+This properly changes the `type` to be a nilable type, as well.
+
+### Array
+
+Oftentimes, if we have a serializer for a single value, we want to serialize an array of values.
+You can use the `#array` method on a serializer to get that.
+Continuing our example from earlier:
+
+```ruby
+my_serializer.array.serialize([Foo.new(10, 11)]) #=> [{ bar: 10, baz: 11 }]
+```
+
+This changes the type properly, too.
+
+## OutputObjects
+
+98% of the time, when we're writing web APIs, we want to transform our domain objects into JSON objects.
+We often want different ways to do this, too.
+Consider, for exmaple, and API for a college.
+We might want to provide one detailed way to serialize a student, which includes their full name, grade, student ID, GPA, and so on.
+On another page, we might want to display a classroom with a list of students.
+However, on the classroom page, we don't want to serialize a full student: that's sending too much data.
+Instead, we probably want to serialize a "stub" view.
+
+OutputObjects are the answer to these problems.
+They're a way to define a serializer for a JSON object, along with a type, and to define "variant" ways to serialize things.
+
+
+### The Basics
+
+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|
+    student.graded_assignments.limit(100).pluck(:grade)
+  end
+end
+```
+
+We can see a few things here:
+
+1. You define field names with a `field` definition, which is a way to define the serializer for a single field.
+2. You must provide types with field names
+3. You can use blocks to do data formatting, which lets you pick different fields and such.
+
+### Views
+
+Sometimes, you might want to add "variant" ways to look at data.
+We call these "views," based on the output objecter concept.
+Let's take a look at their use:
+
+```ruby
+StudentOutputObject = SoberSwag::OutputObject.define do
+  field :first_name, primitive(:String)
+  field :last_name, primitive(:String)
+  view :detail do
+    field :recent_grades, primitive(:Integer).array do |student|
+      student.graded_assignments.limit(100).pluck(:grade)
+    end
+  end
+ end
+
+StudentOutputObject.serialize(my_student) # => { first_name: 'Rich', last_name: 'Evans' }
+StudentOutputObject.serialize(
+  my_student,
+  { view: :detail }
+) # => { first_name: 'Rich', last_name: 'Evans', recent_grades: [0, 0, 0, 1] }
+```
+
+The options hash of the serializer will be used to determine which view to serialize with.
+Handily, each view is actually *its own* serializer.
+You can obtain a serializer for a single view very easily:
+
+```ruby
+StudentOutputObject.view(:detail)
+```
+
+If you want an output object without the view-checking behavior, you can use `.base` on an output object.
+
+```ruby
+StudentOutputObject.base
+```
+
+Both of these are great for defining *relationships* between data.
+
+### Circular OutputObjects
+
+Sometimes, you might want to include an output object inside another output object, that itself has that output object inside it.
+Or, less confusingly, you wanna do this:
+
+```ruby
+StudentOutputObject = SoberSwag::OutputObject.define do
+  # some other fields
+  view :detail do
+    field :classes, ClassOutputObject.array
+  end
+end
+```
+
+This can cause a circular dependency.
+To break this, you can use a lambda:
+
+```ruby
+StudentOutputObject = SoberSwag::OutputObject.define do
+  view :detail do
+    field :classes, -> { ClassOutputObject.view(:base).array }
+  end
+end
+```
+
+For clarity (and to prevent infinitely-looping serializers on accident, we recommend you *always* use an explicit view for dependent output objects.