sober_swag 0.11.0 → 0.16.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c07baa6165df700b23c0f8a0c9bd1a1dcb841d79b07995479b0c1e19a69928d7
-  data.tar.gz: 523a0eabeb954497f531485962b0f058dc9a32ec398df899162c66e5d985d01e
+  metadata.gz: ad86b8f4701d16ec53f0fc998bb2a881cdc448acfbb509bbfeb7821cc7142d1b
+  data.tar.gz: ce70ffa29ca02b8fc70e7f78c0b41bf56e8e3cdffbcf7282d8dad1cf16717b23
 SHA512:
-  metadata.gz: 0ccf5c1f96d1647e42e082bfdd05c0a0ba3ff9d6d0bbe9139f9349bd17c917e854057af26a073c84aeeb54ac065c8c9f297d99d8063a0bccf032f77217c900bd
-  data.tar.gz: f01787f76223c896154312b43862ac1276154715c9b8234a761c84dc046a1f5ab7f82e387c821805bf2f3b22ed99452bd834336dfdfc8f15350345efcc575de8
+  metadata.gz: '081ef6717877b1c40682fbcbf1436a7e44fd51307a03650edc9a6d4a594a99bc4e9f07adbb73a9073f784aa75dc6a5463f0aa1d77b77fefc976c0531273ced22'
+  data.tar.gz: c1fb5da8a19b9d6ee1324badbbff4caac4db49349efd301b9daaa74097372f2241e174617af5b59970b467610145419b6e392b579fc4a3457073439e5ec6824e

data/.github/workflows/lint.yml

@@ -1,15 +1,50 @@
-name: Linters
+# This workflow uses actions that are not certified by GitHub.
+# They are provided by a third-party and are governed by
+# separate terms of service, privacy policy, and support
+# documentation.
+# This workflow will download a prebuilt Ruby version, install dependencies and run tests with Rake
+# For more information see: https://github.com/marketplace/actions/setup-ruby-jruby-and-truffleruby
 
-on: [push]
+name: Ruby Lint
+
+on:
+  push:
+    branches: [ master ]
+  pull_request:
+    branches: [ master ]
 
 jobs:
-  build:
+  test:
+
     runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        ruby: [ '2.6', '2.7' ]
+
     steps:
-    - uses: actions/checkout@v1
-    - name: Rubocop Linter
-      uses: andrewmcodes/rubocop-linter-action@v3.0.0
+    - uses: actions/checkout@v2
+    - name: Set up Ruby
+    # To automatically get bug fixes and new Ruby versions for ruby/setup-ruby,
+    # change this to (see https://github.com/ruby/setup-ruby#versioning):
+    # uses: ruby/setup-ruby@v1
+      uses: ruby/setup-ruby@ec106b438a1ff6ff109590de34ddc62c540232e0
+      with:
+        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 config path vendor/bundle
+        bundle install
+    - name: Run Lints
+      run: bundle exec rubocop -P
+    - uses: actions/cache@v2
       with:
-        action_config_path: '.github/config/rubocop_linter_action.yml' # Note: this is the default location
-      env:
-        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        path: example/vendor/bundle
+        key: ${{ runner.os }}-${{ matrix.ruby }}-example-deps-${{ hashFiles('example/**/Gemfile.lock') }}
+        restore-keys: |
+          ${{ runner.os }}-${{ matrix.ruby }}-example-deps-

data/.gitignore

@@ -13,3 +13,5 @@
 Gemfile.lock
 
 *.gem
+
+/vendor/

data/.rubocop.yml

@@ -1,81 +1,126 @@
-Style/FrozenStringLiteralComment:
-  Enabled: false
-Style/BlockDelimiters:
-  EnforcedStyle: braces_for_chaining
+require: rubocop-rspec
+
 AllCops:
   TargetRubyVersion: 2.6.0
   Exclude:
     - 'bin/bundle'
     - 'example/bin/bundle'
+    - 'vendor/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
+
+RSpec/LeadingSubject:
+  Enabled: false
+
 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
+
+RSpec/NestedGroups:
+  Max: 5
+
+RSpec/ExampleLength:
+  Max: 10
+
+Style/FrozenStringLiteralComment:
+  Enabled: false
+
+Style/BlockDelimiters:
+  EnforcedStyle: braces_for_chaining

data/CHANGELOG.md

@@ -0,0 +1,22 @@
+# Changelog
+
+## [v0.16.0]: 2020-10-23
+
+- Allow non-class types to be used as the inputs to controllers
+
+## [v0.15.0]: 2020-09-02
+
+### Added
+- Add a new `#merge` method to output objects, which will merge fields from another output object into the given output object.
+- Add `multi` to Output Objects, as a way to define more than one field of the same type at once.
+- Add an `inherits:` key to output objects, for view inheritance.
+- Add `SoberSwag::Types::CommaArray`, which parses comma-separated strings into arrays.
+  This also sets `style` to `form` and `explode` to `false` when generating Swagger docs.
+  This class is mostly useful for query parameters where you want a simpler format: `tag=foo,bar` instead of `tag[]=foo,tag[]=bar`.
+- Add support for using `meta` to specify alternative `style` and `explode` keys for query and path params.
+  Note that this support *does not* extend to parsing: If you modify the `style` or `explode` keywords, you will need to make those input formats work with the actual type yourself.
+
+### Fixed
+- No longer swallow `Dry::Struct` errors, instead let them surface to the user.
+
+[v0.15.0]: https://github.com/SonderMindOrg/sober_swag/releases/tag/v0.15.0

data/README.md

@@ -9,6 +9,10 @@ This generates documentation from *types*, which (conveniently) also lets you ge
 
 An introductory presentation is available [here](https://www.icloud.com/keynote/0bxP3Dn8ETNO0lpsSQSVfEL6Q#SoberSwagPresentation).
 
+Further documentation on using the gem is available in the `docs/` directory:
+
+- [Serializers](docs/serializers.md)
+
 ## Types for a fully-automated API
 
 SoberSwag lets you type your API using describe blocks.
@@ -18,7 +22,14 @@ This lets you type your API endpoint:
 ```ruby
 class PeopleController < ApplicationController
   include SoberSwag::Controller
+
   define :patch, :update, '/people/{id}' do
+    summary 'Update a Person record.'
+    description <<~MARKDOWN
+      You can use this endpoint to update a Person record. Note that age cannot
+      be a negative integer.
+    MARKDOWN
+
     query_params do
       attribute? :include_extra_info, Types::Params::Bool
     end
@@ -28,11 +39,13 @@ class PeopleController < ApplicationController
     end
     path_params { attribute :id, Types::Params::Integer }
   end
+  def update
+    # update action here
+  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:
+Then we can use the information from our SoberSwag definition *inside* the controller method:
 
 ```ruby
 def update
@@ -44,6 +57,51 @@ 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.
 
+### Rendering Swagger documentation from SoberSwag
+
+We can also use the information from SoberSwag objects to generate Swagger
+documentation, available at the `swagger` action on this controller.
+
+You can create the `swagger` action for a controller as follows:
+
+```ruby
+# config/routes.rb
+Rails.application.routes.draw do
+  # Add a `swagger` GET endpoint to render the Swagger documentation created
+  # by SoberSwag.
+  resources :people do
+    get :swagger, on: :collection
+  end
+
+  # Or use a concern to make it easier to enable swagger endpoints for a number
+  # of controllers at once.
+  concern :swaggerable do
+    get :swagger, on: :collection
+  end
+
+  resources :people, concerns: :swaggerable do
+    get :search, on: :collection
+  end
+
+  resources :places, only: [:index], concerns: :swaggerable
+end
+```
+
+If you don't want the API documentation to show up in certain cases, you can
+use an environment variable or a check on the current Rails environment.
+
+```ruby
+# config/routes.rb
+Rails.application.routes.draw do
+  resources :people do
+    # Enable based on environment variable.
+    get :swagger, on: :collection if ENV['ENABLE_SWAGGER']
+    # Or just disable in production.
+    get :swagger, on: :collection unless Rails.env.production?
+  end
+end
+```
+
 ### Typed Responses
 
 Want to go further and type your responses too?
@@ -53,6 +111,8 @@ Use SoberSwag output objects, a serializer library heavily inspired by [Blueprin
 PersonOutputObject = SoberSwag::OutputObject.define do
   field :id, primitive(:Integer)
   field :name, primitive(:String).optional
+  # For fields that don't map to a simple attribute on your model, you can
+  # use a block.
   field :is_registered, primitive(:Bool) do |person|
     person.registered?
   end
@@ -95,7 +155,7 @@ 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
+  # use .optional if attributes may be nil
   attribute :age, SoberSwag::Types::Params::Integer.optional
 end
 ```
@@ -120,6 +180,63 @@ 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.
 
+#### Nested object attributes
+
+You can nest attributes using a block. They'll return as nested JSON objects.
+
+```ruby
+User = SoberSwag.input_object do
+  attribute :user_notes do
+    attribute :note, SoberSwag::Types::String
+  end
+end
+```
+
+If you want to use a specific type of object within an input object, you can
+nest them by setting the other input object as the type of an attribute. For
+example, if you had a UserGroup object with various Users, you could write
+them like this:
+
+```ruby
+User = SoberSwag.input_object do
+  attribute :name, SoberSwag::Types::String
+  attribute :age, SoberSwag::Types::Params::Integer.optional
+end
+
+UserGroup = SoberSwag.input_object do
+  attribute :name, SoberSwag::Types::String
+  attribute :users, SoberSwag::Types::Array.of(User)
+end
+```
+
+#### Input and Output Object Identifiers
+
+Both input objects and output objects accept an identifier, which is used in
+the Swagger Documentation to disambiguate between SoberSwag types.
+
+```ruby
+User = SoberSwag.input_object do
+  identifier 'User'
+
+  attribute? :name, SoberSwag::Types::String
+end
+```
+
+```ruby
+PersonOutputObject = SoberSwag::OutputObject.define do
+  identifier 'PersonOutput'
+
+  field :id, primitive(:Integer)
+  field :name, primitive(:String).optional
+end
+```
+
+You can use these to make your Swagger documentation a bit easier to follow,
+and it can also be useful for 'namespacing' objects if you're developing in
+a large application, e.g. if you had a pet store and for some reason users
+with cats and users with dogs were different, you could namespace it with
+`identifier 'Dogs.User'`.
+
 #### Adding additional documentation
 
 You can use the `.meta` attribute on a type to add additional documentation.
@@ -151,10 +268,30 @@ QueryInput = SoberSwag.input_object do
 end
 ```
 
+## Testing the validity of output objects
+
+If you're using RSpec and want to test the validity of output objects, you can do so relatively easily.
+
+For example, assuming that you have a `UserOutputObject` class for representing a User record, and you have a `:user` factory via FactoryBot, you can validate that the serialization works without error like so:
+
+```ruby
+RSpec.describe UserOutputObject do
+  describe 'serialized result' do
+    subject do
+      described_class.type.new(described_class.serialize(create(:user)))
+    end
+
+    it 'works with an object' do
+      expect { subject }.not_to raise_error
+    end
+  end
+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).
+Generating the swagger documentation 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,48 +1,36 @@
 #!/usr/bin/env ruby
-# frozen_string_literal: true
 
 require 'bundler/setup'
 require 'sober_swag'
-
-# 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.
-module Types
-  include Dry.Types()
-end
+require 'pry'
 
 Bio = SoberSwag.input_object do
-  attribute :name, primitive(:String).meta(description: 'A very basic bio name')
+  attribute :description, SoberSwag::Types::String
+  attribute :gender, SoberSwag::Types::String.enum('male', 'female') | SoberSwag::Types::String
 end
 
 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 :name, SoberSwag::Types::String
+  attribute? :bio, Bio.optional
 end
 
-##
-# Demonstration of subclass-style.
-class PersonSearch < SoberSwag::InputObject
-  attribute? :name, Types::String
-  attribute? :age, Types::Integer
+MultiFloorLocation = SoberSwag.input_object do
+  attribute :building, SoberSwag::Types::String.enum('science', 'mathematics', 'literature')
+  attribute :floor, SoberSwag::Types::String
+  attribute :room, SoberSwag::Types::Integer
 end
 
-##
-# Demonstration of subclass-style *and* recursion in structs.
-class LinkedList < SoberSwag::InputObject
-  attribute :value, Types::String
-  attribute? :next, LinkedList
+SingleFloorLocation = SoberSwag.input_object do
+  attribute :building, SoberSwag::Types::String.enum('philosophy', 'computer science')
+  attribute :room, SoberSwag::Types::Integer
 end
 
-Foo = SoberSwag::OutputObject.define do
-  field :name, primitive(:String)
-  field :age, primitive(:String)
-
-  view :foo do
-    field :bar, primitive(:String).optional
-  end
+SchoolClass = SoberSwag.input_object do
+  attribute :prof, Person.meta(description: 'The person who teaches this class.')
+  attribute :students, SoberSwag::Types::Array.of(Person)
+  attribute :location, (SingleFloorLocation | MultiFloorLocation).meta(description: 'What building and room this is in')
 end
 
-# (If you use this, don't forget to add pry to your Gemfile!)
-require 'pry'
+SortDirections = SoberSwag::Types::CommaArray.of(SoberSwag::Types::String.enum('created_at', 'updated_at', '-created_at', '-updated_at'))
+
 Pry.start