sober_swag 0.12.0 → 0.17.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fa0e0e510ec9344738f12f01098f1d34557ac41c83dc966b4368b1407496b868
-  data.tar.gz: 50f62bed3de241407e3d16caaae632dc8af21781477ac7e212a60af71780c932
+  metadata.gz: 7a0e2ee1acc571a7f6a90db87f4c15b6d7d820f24b75abd3f37cb369d431f271
+  data.tar.gz: 6384f275b7b1bd21ef35f4972b519be59a19d1a5e24a5c2138e203748a9702bb
 SHA512:
-  metadata.gz: 04ad84a03ee992677593aeea1342ddbb1fb693d7f67ae6c9e3b31b8d5050aeda86d71f65390d906ade4d30e458cdb7717d3ef02d93f3e966a92e4fac63240e8e
-  data.tar.gz: 535711fae0cc27c5122f5873cf64901e571631d9d87ecc04d44420deb99ff173bf83c0b36cdd34ce44aa6a697cec643098a8784be2487c2f9619ea78b52b2754
+  metadata.gz: c1d8b82b62dc05656482b0e550bc5edb24cdf76dde9dc9bcd4729381c5439983df7e98704eb9a0d54964f70297c8097b8192a016736db5ffff3126849d5425e9
+  data.tar.gz: f55485cc2dd04c4dd414b7c2b5668be91d1c8ada7ad51cf20d04bad62925054d27f940caf83c6c83e1763928c3ea5295d9c592b7a83f85e133cdfbaca697652c

data/.github/workflows/lint.yml

@@ -1,15 +1,47 @@
-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
+      uses: ruby/setup-ruby@v1
+      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/.github/workflows/ruby.yml

@@ -20,14 +20,10 @@ jobs:
     strategy:
       matrix:
         ruby: [ '2.6', '2.7' ]
-
     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,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,26 @@
+# Changelog
+
+## [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.
+  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,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).