sober_swag 0.19.0 → 0.20.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 63ab4c5db5ca2e6fe63713b7416d127b3bdc730e82562d4ca13b477eaf362460
-  data.tar.gz: ce6351db33dc3506be6baa66e228532bd8e3830c9e7b67b27c2c6b899a77677c
+  metadata.gz: 97cb4bbfd84f28f6f79368c3f78182835217868a1d3142c38107ab3b03552952
+  data.tar.gz: 1cd8446250a8ddadc16eb114a773b9d317c2182e2bcb8c692c59681331ef972b
 SHA512:
-  metadata.gz: bab9a59d19cef6552f33555a5cac081c750df97f0364d06fb39fbd5ad4973262f43ca233d52be1f0544815830345a59574dd4913ca2ec6cb2ef7f9e465502f35
-  data.tar.gz: f0e3db070ac4b30457d309d68a88c81b2cb090478553a622f9463e8cff9f3f67bb128f120ebcd9ce73164f21fb2e83b4a8befa02e87779e241fae96188ccc077
+  metadata.gz: f6b055ea451db16f12a02ebe2bc6da459aefcf13605a54f4f0b0cff8aa694b73e2c4cb2c2f759a89c859a820a74a37391728998e0939a770cda2783c2190586e
+  data.tar.gz: 3a49c153297750447c2776b086da135b81c80a1b628780d9a7ab6f68f204ddeaa3b21e08ffd02f8a49e92f1a7ac5942b0e42d295307299e8623ebb6a765731dd

data/.github/workflows/lint.yml

@@ -19,7 +19,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        ruby: [ '2.6', '2.7' ]
+        ruby: [ '2.6', '2.7', '3.0' ]
 
     steps:
     - uses: actions/checkout@v2

data/.github/workflows/ruby.yml

@@ -19,7 +19,7 @@ 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

data/.gitignore

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

data/.rubocop.yml

@@ -2,6 +2,7 @@ require: rubocop-rspec
 
 AllCops:
   TargetRubyVersion: 2.6.0
+  NewCops: enable
   Exclude:
     - 'bin/bundle'
     - 'example/bin/bundle'
@@ -22,6 +23,9 @@ Metrics/BlockLength:
     - 'sober_swag.gemspec'
     - 'example/spec/**/*.rb'
 
+Lint/MissingSuper:
+  Enabled: false
+
 RSpec/ImplicitBlockExpectation:
   Enabled: false
 
@@ -123,4 +127,4 @@ Style/FrozenStringLiteralComment:
   Enabled: false
 
 Style/BlockDelimiters:
-  EnforcedStyle: braces_for_chaining
+  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,5 +1,10 @@
 # Changelog
 
+## [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

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

@@ -11,7 +11,7 @@ An introductory presentation is available [here](https://www.icloud.com/keynote/
 
 Further documentation on using the gem is available in the `docs/` directory:
 
-- [Serializers](docs/serializers.md)
+- {file:docs/serializers.md Serializers}
 
 ## Types for a fully-automated API
 

data/docs/serializers.md

@@ -241,6 +241,9 @@ end
 Using `#merge` lets you add in all the fields from one output object into another.
 You can even use `merge` from within a view.
 
+Exclude any unneeded fields from the merge by passing a hash:
+`merge GenericBioOutput, { except: [:position] }`
+
 Note that `merge` does *not* copy anything but fields.
 Identifiers and views will not be copied over.
 

data/example/Gemfile

@@ -34,7 +34,7 @@ group :development, :test do
 end
 
 group :development do
-  gem 'listen', '>= 3.0.5', '< 3.5'
+  gem 'listen', '>= 3.0.5', '< 3.6'
   # Spring speeds up development by keeping your application running in the background. Read more: https://github.com/rails/spring
   gem 'spring'
   gem 'spring-watcher-listen', '~> 2.0.0'

data/example/config/environments/production.rb

@@ -60,7 +60,7 @@ Rails.application.configure do
   # config.logger = ActiveSupport::TaggedLogging.new(Syslog::Logger.new 'app-name')
 
   if ENV['RAILS_LOG_TO_STDOUT'].present?
-    logger           = ActiveSupport::Logger.new(STDOUT)
+    logger           = ActiveSupport::Logger.new($stdout)
     logger.formatter = config.log_formatter
     config.logger    = ActiveSupport::TaggedLogging.new(logger)
   end

data/lib/sober_swag.rb

@@ -9,8 +9,10 @@ require 'sober_swag/version'
 require 'active_support/inflector'
 
 ##
-# Root namespace
+# Root namespace for the SoberSwag Module.
 module SoberSwag
+  ##
+  # Root Error Class for SoberSwag errors.
   class Error < StandardError; end
 
   autoload :Parser, 'sober_swag/parser'
@@ -26,7 +28,10 @@ module SoberSwag
   ##
   # Define a struct of something.
   # Useful to prevent weirdness from autoloading.
+  #
   # @param parent [Class] the base class for the struct (default of {SoberSwag::Struct})
+  # @yieldself [SoberSwag::InputObject]
+  # @return [Class] the input object class generated
   def self.input_object(parent = nil, &block)
     Class.new(parent || SoberSwag::InputObject, &block)
   end

data/lib/sober_swag/compiler.rb

@@ -17,6 +17,8 @@ module SoberSwag
 
     ##
     # Convert a compiler to the overall type definition.
+    #
+    # @return Hash the swagger definition.
     def to_swagger
       {
         paths: path_schemas,
@@ -29,16 +31,23 @@ module SoberSwag
     ##
     # Add a path to be compiled.
     # @param route [SoberSwag::Controller::Route] the route to add.
+    # @return [Compiler] self
     def add_route(route)
       tap { @paths.add_route(route) }
     end
 
+    ##
+    # Get the schema of each object type defined in this Compiler.
+    #
+    # @return [Hash]
     def object_schemas
       @types.map { |v| [v.ref_name, v.object_schema] }.to_h
     end
 
     ##
     # The path section of the swagger schema.
+    #
+    # @return [Hash]
     def path_schemas
       @paths.paths_list(self)
     end
@@ -46,6 +55,9 @@ module SoberSwag
     ##
     # Compile a type to a new, path-params list.
     # This will add all subtypes to the found types list.
+    #
+    # @param type [Class] the type to get a path_params definition for
+    # @return [Hash]
     def path_params_for(type)
       with_types_discovered(type).path_schema
     end
@@ -53,6 +65,9 @@ module SoberSwag
     ##
     # Get the query params list for a type.
     # All found types will be added to the reference dictionary.
+    #
+    # @param type [Class] the type to get the query_params definitions for
+    # @return [Hash]
     def query_params_for(type)
       with_types_discovered(type).query_schema
     end
@@ -60,25 +75,36 @@ module SoberSwag
     ##
     # Get the request body definition for a type.
     # This will always be a ref.
+    #
+    # @param type [Class] the type to get the body definition for
+    # @return [Hash]
     def body_for(type)
       add_type(type)
       Type.new(type).schema_stub
     end
 
     ##
-    # Get the definition of a response type
+    # Get the definition of a response type.
+    #
+    # This is an alias of {#body_for}
+    # @see body_for
     def response_for(type)
       body_for(type)
     end
 
     ##
-    # Get the existing schema for a given type
+    # Get the existing schema for a given type.
+    #
+    # @param type [Class] the type to get the schema for
+    # @return [Hash,nil] the swagger schema for this object, or nil if it was not found.
     def schema_for(type)
       @types.find { |type_comp| type_comp.type == type }&.object_schema
     end
 
     ##
-    # Add a type in the types reference dictionary, essentially
+    # Add a type in the types reference dictionary, essentially.
+    # @param type [Class] the type to compiler
+    # @return [SoberSwag::Compiler] self
     def add_type(type)
       # use tap here to avoid an explicit self at the end of this
       # which makes this method chainable

data/lib/sober_swag/compiler/path.rb

@@ -1,8 +1,11 @@
 module SoberSwag
   class Compiler
     ##
-    # Compile a singular path, and that's it.
-    # Only handles the actual body.
+    # This compiler transforms a {SoberSwag::Controller::Route} object into its associated OpenAPI V3 definition.
+    # These definitions are [called "paths" in the OpenAPI V3 spec](https://swagger.io/docs/specification/paths-and-operations/),
+    # thus the name of this compiler.
+    #
+    # It only compiles a *single* "path" at a time.
     class Path
       ##
       # @param route [SoberSwag::Controller::Route] a route to use
@@ -12,8 +15,18 @@ module SoberSwag
         @compiler = compiler
       end
 
-      attr_reader :route, :compiler
+      ##
+      # @return [SoberSwag::Controller::Route]
+      attr_reader :route
+
+      ##
+      # @return [SoberSwag::Compiler] the compiler used for type compilation
+      attr_reader :compiler
 
+      ##
+      # The OpenAPI V3 "path" object for the associated {SoberSwag::Controller::Route}
+      #
+      # @return [Hash] the OpenAPI V3 description
       def schema
         base = {}
         base[:summary] = route.summary if route.summary
@@ -25,6 +38,11 @@ module SoberSwag
         base
       end
 
+      ##
+      # An array of "response" objects from swagger.
+      #
+      # @return [Hash{String => Hash}]
+      #   response code to response object.
       def responses # rubocop:disable Metrics/MethodLength
         route.response_serializers.map { |status, serializer|
           [
@@ -41,10 +59,19 @@ module SoberSwag
         }.to_h
       end
 
+      ##
+      # An array of all parameters, be they in the query or in the path.
+      # See [this page](https://swagger.io/docs/specification/serialization/) for what that looks like.
+      #
+      # @return [Array<Hash>]
       def params
         query_params + path_params
       end
 
+      ##
+      # An array of schemas for all query parameters.
+      #
+      # @return [Array<Hash>] the schemas
       def query_params
         if route.query_params_class
           compiler.query_params_for(route.query_params_class)
@@ -53,6 +80,10 @@ module SoberSwag
         end
       end
 
+      ##
+      # An array of schemas for all path parameters.
+      #
+      # @return [Array<Hash>] the schemas
       def path_params
         if route.path_params_class
           compiler.path_params_for(route.path_params_class)
@@ -61,6 +92,11 @@ module SoberSwag
         end
       end
 
+      ##
+      # The schema for a request body.
+      # Matches [this spec.](https://swagger.io/docs/specification/paths-and-operations/)
+      #
+      # @return [Hash] the schema
       def request_body
         return nil unless route.request_body_class
 
@@ -74,6 +110,9 @@ module SoberSwag
         }
       end
 
+      ##
+      # The tags for this path.
+      # @return [Array<String>] the tags
       def tags
         return nil unless route.tags.any?
 

data/lib/sober_swag/compiler/paths.rb

@@ -2,15 +2,28 @@ module SoberSwag
   class Compiler
     ##
     # Compile multiple routes into a paths set.
+    # This basically just aggregates {SoberSwag::Controller::Route} objects.
     class Paths
+      ##
+      # Set up a new paths compiler with no routes in it.
       def initialize
         @routes = []
       end
 
+      ##
+      # Add on a new {SoberSwag::Controller::Route}
+      #
+      # @param route [SoberSwag::Controller::Route] the route description to add to compilation
+      # @return [SoberSwag::Compiler::Paths] self
       def add_route(route)
         @routes << route
+
+        self
       end
 
+      ##
+      # In the OpenAPI V3 spec, we group action definitions by their path.
+      # This helps us do that.
       def grouped_paths
         routes.group_by(&:path)
       end
@@ -20,6 +33,9 @@ module SoberSwag
       # paths list. Since this is only a compiler for paths,
       # it has *no idea* how to handle types. So, it takes a compiler
       # which it will use to do that for it.
+      #
+      # @param compiler [SoberSwag::Compiler::Type] the type compiler to use
+      # @return [Hash] a schema for all contained routes.
       def paths_list(compiler)
         grouped_paths.transform_values do |values|
           values.map { |route|
@@ -31,6 +47,8 @@ module SoberSwag
       ##
       # Get a list of all types we discovered when compiling
       # the paths.
+      #
+      # @yield [Class] all the types found in all the routes described in here.
       def found_types
         return enum_for(:found_types) unless block_given?
 
@@ -41,6 +59,8 @@ module SoberSwag
         end
       end
 
+      ##
+      # @return [Array<SoberSwag::Controller::Route>] the routes to document
       attr_reader :routes
 
       private

data/lib/sober_swag/compiler/primitive.rb

@@ -4,7 +4,11 @@ module SoberSwag
     # Compiles a primitive type.
     # Almost always constructed with the values from
     # {SoberSwag::Nodes::Primitive}.
+    #
+    # This works by either generating a swagger primitive definition, *or* a `$ref` to one with a given identifier.
     class Primitive
+      ##
+      # @param type [Class] the swagger-able class to document.
       def initialize(type)
         @type = type
 
@@ -13,6 +17,8 @@ module SoberSwag
 
       attr_reader :type
 
+      ##
+      # Is this documenting one of the build-in swagger types?
       def swagger_primitive?
         SWAGGER_PRIMITIVE_DEFS.include?(type)
       end
@@ -25,6 +31,9 @@ module SoberSwag
 
       ##
       # Turn this type into a swagger hash with a proper type key.
+      # This is suitable for use as the value of a `schema` key in a definition.
+      #
+      # @return [Hash] the schema.
       def type_hash
         if swagger_primitive?
           SWAGGER_PRIMITIVE_DEFS.fetch(type)
@@ -37,10 +46,16 @@ module SoberSwag
         end
       end
 
+      ##
+      # Primitive schema used for ruby `Date` values.
       DATE_PRIMITIVE = { type: :string, format: :date }.freeze
+      ##
+      # Primitive schema used for ruby `DateTime` values.
       DATE_TIME_PRIMITIVE = { type: :string, format: :'date-time' }.freeze
       HASH_PRIMITIVE = { type: :object, additionalProperties: true }.freeze
 
+      ##
+      # Map of types that are considered "primitive types" in the OpenAPI V3 spec.
       SWAGGER_PRIMITIVE_DEFS =
         {
           NilClass => :null,
@@ -57,6 +72,8 @@ module SoberSwag
           Hash => HASH_PRIMITIVE
         ).transform_values(&:freeze).freeze
 
+      ##
+      # @return [String] the schema reference
       def ref_name
         raise Error, 'is not a type that is named!' if swagger_primitive?