sober_swag 0.15.0 → 0.20.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ff24aa407a6b8360569931c050bee2958cb6e3169f34f57f1d455f0d573327af
-  data.tar.gz: 61bf1feb701ae67e2a2fd85f41ab2d8ccd25d5e512a4cd26e3849f65e78a14e9
+  metadata.gz: 97cb4bbfd84f28f6f79368c3f78182835217868a1d3142c38107ab3b03552952
+  data.tar.gz: 1cd8446250a8ddadc16eb114a773b9d317c2182e2bcb8c692c59681331ef972b
 SHA512:
-  metadata.gz: 46c72426dcabb170bf8c5416e8583c254a9c627f8a6cf48424145dc688c9abcb2f7c6e61c87c55da0b8f66f9d076254cce3f815616c9f03eaa88aa14b19c72e4
-  data.tar.gz: a13ac7c92fdaec126d93a3400e13f93287c993bd19c82caa76cc662112e82983a64de5233adfce1cd30a32bfdca6ecc794b5f06a15f7cc2ffda0bbd155b1d0a5
+  metadata.gz: f6b055ea451db16f12a02ebe2bc6da459aefcf13605a54f4f0b0cff8aa694b73e2c4cb2c2f759a89c859a820a74a37391728998e0939a770cda2783c2190586e
+  data.tar.gz: 3a49c153297750447c2776b086da135b81c80a1b628780d9a7ab6f68f204ddeaa3b21e08ffd02f8a49e92f1a7ac5942b0e42d295307299e8623ebb6a765731dd

data/.github/dependabot.yml

@@ -0,0 +1,15 @@
+# To get started with Dependabot version updates, you'll need to specify which
+# package ecosystems to update and where the package manifests are located.
+# Please see the documentation for all configuration options:
+# https://help.github.com/github/administering-a-repository/configuration-options-for-dependency-updates
+
+version: 2
+updates:
+  - package-ecosystem: "bundler"
+    directory: "/"
+    schedule:
+      interval: "daily"
+  - package-ecosystem: "bundler"
+    directory: "/example" 
+    schedule:
+      interval: "daily"

data/.github/workflows/lint.yml

@@ -19,17 +19,14 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        ruby: [ '2.6', '2.7' ]
+        ruby: [ '2.6', '2.7', '3.0' ]
 
     steps:
     - 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
+      uses: ruby/setup-ruby@v1
       with:
-        ruby-version:  ${{ matrix.ruby }}
+        ruby-version: ${{ matrix.ruby }}
     - uses: actions/cache@v2
       with:
         path: vendor/bundle
@@ -40,10 +37,8 @@ jobs:
       run: |
         bundle config path vendor/bundle
         bundle install
-        gem install rubocop
-        gem install rubocop-rspec
     - name: Run Lints
-      run: rubocop lib spec example
+      run: bundle exec rubocop -P
     - uses: actions/cache@v2
       with:
         path: example/vendor/bundle

data/.github/workflows/ruby.yml

@@ -19,15 +19,11 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        ruby: [ '2.6', '2.7' ]
-
+        ruby: [ '2.6', '2.7', '3.0' ]
     steps:
     - 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
+      uses: ruby/setup-ruby@v1
       with:
         ruby-version:  ${{ matrix.ruby }}
     - uses: actions/cache@v2

data/.gitignore

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

data/.rubocop.yml

@@ -1,85 +1,130 @@
-Style/FrozenStringLiteralComment:
-  Enabled: false
-Style/BlockDelimiters:
-  EnforcedStyle: braces_for_chaining
+require: rubocop-rspec
+
 AllCops:
   TargetRubyVersion: 2.6.0
+  NewCops: enable
   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'
+
+Lint/MissingSuper:
+  Enabled: false
+
 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/.yardopts

@@ -0,0 +1,7 @@
+--markup-provider=redcarpet
+--markup=markdown
+--plugin activesupport-concern
+--plugin solargraph
+--private
+--protected
+--files docs/serializers.md

data/CHANGELOG.md

@@ -1,7 +1,30 @@
 # Changelog
 
-## V0.15.0: 2020-09-02
+## [v0.20.0] 2021-05-17
 
+- Added YARD documentation to almost every method
+- Added `except` parameter to the `merge` method, which allows a specified field to be excluded from the merge.
+
+## [v0.19.0] 2021-03-10
+
+- Use [redoc](https://github.com/Redocly/redoc) for generated documentation UI
+
+## [v0.18.0] 2021-03-02
+
+- Add generic hash type for primitive types
+
+## [v0.17.0]: 2020-11-30
+
+- Allow tagging endpoints via the new `tags` method.
+
+## [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.
@@ -9,3 +32,8 @@
   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/Gemfile

@@ -4,3 +4,11 @@ source 'https://rubygems.org'
 
 # Specify your gem's dependencies in sober_swag.gemspec
 gemspec
+
+gem 'yard'
+
+gem 'redcarpet'
+
+gem 'yard-activesupport-concern'
+
+gem 'solargraph'

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:
+
+- {file:docs/serializers.md Serializers}
+
 ## 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,44 @@ QueryInput = SoberSwag.input_object do
 end
 ```
 
+## Tags
+
+If you want to organize your API into sections, you can use `tags`.
+It's quite simple:
+
+```ruby
+define :patch, :update, '/people/{id}' do
+  # other cool config
+  tags 'people', 'mutations', 'incurs_cost'
+end
+```
+
+This will map to OpenAPI's `tags` field (naturally), and the UI codegen will automatically organize your endpoints by their tags.
+
+## 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).