sober_swag 0.15.0 → 0.20.0

data/bin/rspec

@@ -0,0 +1,29 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+#
+# This file was generated by Bundler.
+#
+# The application 'rspec' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+require 'pathname'
+ENV['BUNDLE_GEMFILE'] ||= File.expand_path('../../Gemfile',
+                                           Pathname.new(__FILE__).realpath)
+
+bundle_binstub = File.expand_path('bundle', __dir__)
+
+if File.file?(bundle_binstub)
+  if File.read(bundle_binstub, 300) =~ /This file was generated by Bundler/
+    load(bundle_binstub)
+  else
+    abort("Your `bin/bundle` was not generated by Bundler, so this binstub cannot run.
+Replace `bin/bundle` by running `bundle binstubs bundler --force`, then run this command again.")
+  end
+end
+
+require 'rubygems'
+require 'bundler/setup'
+
+load Gem.bin_path('rspec-core', 'rspec')

data/docs/serializers.md

@@ -25,21 +25,21 @@ For example, you might have a serializer that can return a date in two formats,
 In this case, it might be used as:
 
 ```ruby
-serializer.new(my_record, { format: :newstyle })
+serializer.new(my_record, { format: :new_style })
 ```
 
 However, since it is *always* optional, you can also do:
 
 ```ruby
-serilaizer.new(my_record)
+serializer.new(my_record)
 ```
 
 And it *should* pick some default format.
 
 ### Primitives
 
-Primitive serializers, or "identity serializers," are serializers that do nothing.
-They are implemented as [`SoberSwag::Serializer::Primitive`](../lib/sober_swag/serializer/primitive.rb), or as the `#primitive` method on a `OutputObject`.
+Primitive serializers — or "identity serializers" — are serializers that do nothing.
+They are implemented as [`SoberSwag::Serializer::Primitive`](../lib/sober_swag/serializer/primitive.rb), or as the `#primitive` method on an `OutputObject`.
 Since they don't do anything, they can be considered the most "basic" serializer.
 
 These serializers *do not* check types.
@@ -51,12 +51,12 @@ serializer.serialize(10) # => 10
 ```
 
 Thus, care should be used when working with these serializers.
-In the future, we might add some "debug mode" sorta thing that will do type-checking and throw errors, however, the cost of doing so in production is probably not worth it.
+In the future, we might add some "debug mode" thing that will do type-checking and throw errors, however, the cost of doing so in production is probably not worth it.
 
 ### Mapped
 
 Sometimes, you can create a serializer via a *proc*.
-For example, let's say that I want a serializer that takes a `Date` and returns a string.
+For example, let's say that I want a serializer that takes a `Date` and returns a String.
 I can do this:
 
 ```ruby
@@ -74,7 +74,7 @@ In the future, we might add a debug mode.
 Oftentimes, we want to give a serializer the ability to serialize `nil` values.
 This is often useful in serializing fields.
 
-It turns out that it's pretty easy to make a serializer that can serialize `nil` values: just propogate nils.
+It turns out that it's pretty easy to make a serializer that can serialize `nil` values: just propogate `nil`s.
 For example, let's say I have the following code:
 
 ```ruby
@@ -99,7 +99,7 @@ Continuing our example from earlier:
 my_serializer.array.serialize([Foo.new(10, 11)]) #=> [{ bar: 10, baz: 11 }]
 ```
 
-This changes the type properly, too.
+This changes the type properly too.
 
 ## OutputObjects
 
@@ -132,7 +132,7 @@ end
 We can see a few things here:
 
 1. You define field names with a `field` definition, which is a way to define the serializer for a single field.
-2. You must provide types with field names
+2. You must provide types with field names.
 3. You can use blocks to do data formatting, which lets you pick different fields and such.
 
 
@@ -223,12 +223,12 @@ For clarity (and to prevent infinitely-looping serializers on accident, we recom
 Output objects don't support inheritance.
 You can't have one output object based on another.
 You *can*, however, merge one into another!
-Consdier this case:
+Consider this case:
 
 ```ruby
 GenericBioOutput = SoberSwag::OutputObject.define do
   field :name, primitive(:String)
-  field :brief_history, primtiive(:String)
+  field :brief_history, primitive(:String)
 end
 
 ExecutiveBioOutput = SoberSwag::OutputObject.define do
@@ -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.
 
@@ -248,14 +251,16 @@ Identifiers and views will not be copied over.
 
 While defining a new Output Object, you *do not* have access to the definition of that output object.
 So, how do I say that one view should be an extension of another?
-Simple: use the `inherits:` kwarg:
+Simple, use the `inherits:` kwarg:
 
 ```ruby
 BioOutput = SoberSwag::OutputObject.define do
   field :name, primitive(:String)
+
   view :detail do
     field :bio, primitive(:String)
   end
+
   view :super_detail, inherits: :detail do
     field :age, primitive(:Integer)
   end
@@ -263,4 +268,4 @@ end
 ```
 
 `inherits` will automatically merge in all the fields of the referenced view.
-This means that the view `super_detail`  will include fields `name`, `bio`, and `age`.
+This means that the view `super_detail` will include fields `name`, `bio`, and `age`.

data/example/Gemfile

@@ -8,7 +8,7 @@ gem 'actionpack', '>= 6.0.3.2'
 # Use sqlite3 as the database for Active Record
 gem 'sqlite3', '~> 1.4'
 # Use Puma as the app server
-gem 'puma', '~> 4.3'
+gem 'puma', '~> 5.2'
 # Build JSON APIs with ease. Read more: https://github.com/rails/jbuilder
 # gem 'jbuilder', '~> 2.7'
 # Use Active Model has_secure_password
@@ -34,7 +34,7 @@ group :development, :test do
 end
 
 group :development do
-  gem 'listen', '>= 3.0.5', '< 3.2'
+  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/app/controllers/people_controller.rb

@@ -35,6 +35,7 @@ class PeopleController < ApplicationController
     request_body(PersonParams)
     response(:ok, 'the person created', PersonOutputObject)
     response(:unprocessable_entity, 'the validation errors', PersonErrorsOutputObject)
+    tags 'people', 'create'
   end
   def create
     p = Person.new(parsed_body.person.to_h)
@@ -50,6 +51,7 @@ class PeopleController < ApplicationController
     path_params { attribute :id, Types::Params::Integer }
     response(:ok, 'the person updated', PersonOutputObject)
     response(:unprocessable_entity, 'the validation errors', PersonErrorsOutputObject)
+    tags 'people', 'update'
   end
   def update
     if @person.update(parsed_body.person.to_h)
@@ -68,6 +70,7 @@ class PeopleController < ApplicationController
       attribute :view, Types::String.default('base'.freeze).enum('base', 'detail')
     end
     response(:ok, 'all the people', PersonOutputObject.array)
+    tags 'people', 'list'
   end
   def index
     @people = Person.all
@@ -81,6 +84,7 @@ class PeopleController < ApplicationController
       attribute :id, Types::Params::Integer
     end
     response(:ok, 'the person requested', PersonOutputObject)
+    tags 'people', 'show'
   end
   def show
     respond!(:ok, @person)

data/example/app/controllers/posts_controller.rb

@@ -47,6 +47,7 @@ class PostsController < ApplicationController
       MARKDOWN
     end
     response(:ok, 'all the posts', PostOutputObject.array)
+    tags 'posts', 'list'
   end
   def index
     @posts = Post.all
@@ -60,6 +61,7 @@ class PostsController < ApplicationController
     path_params(ShowPath)
     query_params { attribute? :view, ViewTypes }
     response(:ok, 'the requested post', PostOutputObject)
+    tags 'posts', 'show'
   end
   def show
     respond!(:ok, @post, serializer_opts: { view: parsed_query.view })
@@ -68,6 +70,7 @@ class PostsController < ApplicationController
   define :post, :create, '/posts/' do
     request_body(PostCreate)
     response(:created, 'the created post', PostOutputObject)
+    tags 'posts', 'create'
   end
   def create
     @post = Post.new(parsed_body.post.to_h)
@@ -83,6 +86,7 @@ class PostsController < ApplicationController
     path_params(ShowPath)
     request_body(PostUpdate)
     response(:ok, 'the post updated', PostOutputObject.view(:base))
+    tags 'posts', 'update'
   end
   def update
     if @post.update(parsed_body.post.to_h)
@@ -95,6 +99,7 @@ class PostsController < ApplicationController
   define :delete, :destroy, '/posts/{id}' do
     path_params(ShowPath)
     response(:ok, 'the post deleted', PostOutputObject.view(:base))
+    tags 'posts', 'delete'
   end
   def destroy
     @post.destroy

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
@@ -21,9 +34,15 @@ module SoberSwag
         base[:parameters] = params if params.any?
         base[:responses] = responses
         base[:requestBody] = request_body if request_body
+        base[:tags] = tags if tags
         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|
           [
@@ -40,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)
@@ -52,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)
@@ -60,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
 
@@ -72,6 +109,15 @@ module SoberSwag
           }
         }
       end
+
+      ##
+      # The tags for this path.
+      # @return [Array<String>] the tags
+      def tags
+        return nil unless route.tags.any?
+
+        route.tags
+      end
     end
   end
 end