sober_swag 0.14.0 → 0.19.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 234da6bca56fd440edae30e4fc9c34c50a37a6ab26b41739276e57ab43c73408
-  data.tar.gz: 103e61429365ceb04d6d0225822ddaa4012f95a043a5bb97c6b8a2fd26671ce5
+  metadata.gz: 63ab4c5db5ca2e6fe63713b7416d127b3bdc730e82562d4ca13b477eaf362460
+  data.tar.gz: ce6351db33dc3506be6baa66e228532bd8e3830c9e7b67b27c2c6b899a77677c
 SHA512:
-  metadata.gz: 58f27a7deebfcb50ec6279084e0a0e872fd0c2a447fca922549d7d3d9822a7e13e010372376c1a079472ba807845d267327275fe453efb99662f685321041e28
-  data.tar.gz: 97ecdb6352db7545004fba2103bb505b3730973a22689f05dedd5b6a305115a63f302f0f248edd3f70e6377ebe470c9ef4f734b2e38af031bf762d229c71bcc0
+  metadata.gz: bab9a59d19cef6552f33555a5cac081c750df97f0364d06fb39fbd5ad4973262f43ca233d52be1f0544815830345a59574dd4913ca2ec6cb2ef7f9e465502f35
+  data.tar.gz: f0e3db070ac4b30457d309d68a88c81b2cb090478553a622f9463e8cff9f3f67bb128f120ebcd9ce73164f21fb2e83b4a8befa02e87779e241fae96188ccc077

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

@@ -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,34 @@
+# Changelog
+
+## [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.
+  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).