sober_swag 0.14.0 → 0.19.0

data/bin/console

@@ -0,0 +1,36 @@
+#!/usr/bin/env ruby
+
+require 'bundler/setup'
+require 'sober_swag'
+require 'pry'
+
+Bio = SoberSwag.input_object do
+  attribute :description, SoberSwag::Types::String
+  attribute :gender, SoberSwag::Types::String.enum('male', 'female') | SoberSwag::Types::String
+end
+
+Person = SoberSwag.input_object do
+  attribute :name, SoberSwag::Types::String
+  attribute? :bio, Bio.optional
+end
+
+MultiFloorLocation = SoberSwag.input_object do
+  attribute :building, SoberSwag::Types::String.enum('science', 'mathematics', 'literature')
+  attribute :floor, SoberSwag::Types::String
+  attribute :room, SoberSwag::Types::Integer
+end
+
+SingleFloorLocation = SoberSwag.input_object do
+  attribute :building, SoberSwag::Types::String.enum('philosophy', 'computer science')
+  attribute :room, SoberSwag::Types::Integer
+end
+
+SchoolClass = SoberSwag.input_object do
+  attribute :prof, Person.meta(description: 'The person who teaches this class.')
+  attribute :students, SoberSwag::Types::Array.of(Person)
+  attribute :location, (SingleFloorLocation | MultiFloorLocation).meta(description: 'What building and room this is in')
+end
+
+SortDirections = SoberSwag::Types::CommaArray.of(SoberSwag::Types::String.enum('created_at', 'updated_at', '-created_at', '-updated_at'))
+
+Pry.start

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,9 +132,25 @@ 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.
 
+
+### Multi
+
+If you have a few fields of the same type, you can use `#multi` to define them all at once:
+
+```ruby
+StudentOutputObject = SoberSwag::OutputObject.define do
+  multi [:first_name, :last_name], primitive(:String)
+  field :recent_grades, primitive(:Integer).array do |student|
+    student.graded_assignments.limit(100).pluck(:grade)
+  end
+end
+```
+
+This saves a bit of typing, and can help with refactoring later.
+
 ### Views
 
 Sometimes, you might want to add "variant" ways to look at data.
@@ -201,3 +217,52 @@ end
 ```
 
 For clarity (and to prevent infinitely-looping serializers on accident, we recommend you *always* use an explicit view for dependent output objects.
+
+### "Inheritance"
+
+Output objects don't support inheritance.
+You can't have one output object based on another.
+You *can*, however, merge one into another!
+Consider this case:
+
+```ruby
+GenericBioOutput = SoberSwag::OutputObject.define do
+  field :name, primitive(:String)
+  field :brief_history, primitive(:String)
+end
+
+ExecutiveBioOutput = SoberSwag::OutputObject.define do
+  merge GenericBioOutput
+  field :company, primitive(:String)
+  field :position, primitive(:String)
+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.
+
+Note that `merge` does *not* copy anything but fields.
+Identifiers and views will not be copied over.
+
+### View Inheritance
+
+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:
+
+```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
+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`.

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.5'
   # 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/application_controller.rb

@@ -1,2 +1,7 @@
+##
+# Standard application controller.
 class ApplicationController < ActionController::API
+  rescue_from Dry::Struct::Error do
+    head :bad_request
+  end
 end

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/lib/sober_swag.rb

@@ -21,6 +21,7 @@ module SoberSwag
   autoload :Controller, 'sober_swag/controller'
   autoload :InputObject, 'sober_swag/input_object'
   autoload :Server, 'sober_swag/server'
+  autoload :Type, 'sober_swag/type'
 
   ##
   # Define a struct of something.

data/lib/sober_swag/compiler.rb

@@ -6,6 +6,7 @@ module SoberSwag
   class Compiler
     autoload(:Type, 'sober_swag/compiler/type')
     autoload(:Error, 'sober_swag/compiler/error')
+    autoload(:Primitive, 'sober_swag/compiler/primitive')
     autoload(:Path, 'sober_swag/compiler/path')
     autoload(:Paths, 'sober_swag/compiler/paths')
 

data/lib/sober_swag/compiler/path.rb

@@ -21,6 +21,7 @@ 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
 
@@ -72,6 +73,12 @@ module SoberSwag
           }
         }
       end
+
+      def tags
+        return nil unless route.tags.any?
+
+        route.tags
+      end
     end
   end
 end

data/lib/sober_swag/compiler/primitive.rb

@@ -0,0 +1,77 @@
+module SoberSwag
+  class Compiler
+    ##
+    # Compiles a primitive type.
+    # Almost always constructed with the values from
+    # {SoberSwag::Nodes::Primitive}.
+    class Primitive
+      def initialize(type)
+        @type = type
+
+        raise Error, "#{type.inspect} is not a class!" unless @type.is_a?(Class)
+      end
+
+      attr_reader :type
+
+      def swagger_primitive?
+        SWAGGER_PRIMITIVE_DEFS.include?(type)
+      end
+
+      ##
+      # Is the wrapped type a named type, causing us to make a ref?
+      def named?
+        type <= SoberSwag::Type::Named
+      end
+
+      ##
+      # Turn this type into a swagger hash with a proper type key.
+      def type_hash
+        if swagger_primitive?
+          SWAGGER_PRIMITIVE_DEFS.fetch(type)
+        else
+          {
+            oneOf: [
+              { '$ref'.to_sym => named_ref }
+            ]
+          }
+        end
+      end
+
+      DATE_PRIMITIVE = { type: :string, format: :date }.freeze
+      DATE_TIME_PRIMITIVE = { type: :string, format: :'date-time' }.freeze
+      HASH_PRIMITIVE = { type: :object, additionalProperties: true }.freeze
+
+      SWAGGER_PRIMITIVE_DEFS =
+        {
+          NilClass => :null,
+          TrueClass => :boolean,
+          FalseClass => :boolean,
+          Float => :number,
+          Integer => :integer,
+          String => :string
+        }.transform_values { |v| { type: v.freeze } }
+        .to_h.merge(
+          Date => DATE_PRIMITIVE,
+          DateTime => DATE_TIME_PRIMITIVE,
+          Time => DATE_TIME_PRIMITIVE,
+          Hash => HASH_PRIMITIVE
+        ).transform_values(&:freeze).freeze
+
+      def ref_name
+        raise Error, 'is not a type that is named!' if swagger_primitive?
+
+        if type <= SoberSwag::Type::Named
+          type.root_alias.identifier
+        else
+          type.name.gsub('::', '.')
+        end
+      end
+
+      private
+
+      def named_ref
+        "#/components/schemas/#{ref_name}"
+      end
+    end
+  end
+end

data/lib/sober_swag/compiler/type.rb

@@ -4,46 +4,6 @@ module SoberSwag
     # A compiler for DRY-Struct data types, essentially.
     # It only consumes one type at a time.
     class Type # rubocop:disable Metrics/ClassLength
-      class << self
-        def get_ref(klass)
-          "#/components/schemas/#{safe_name(klass)}"
-        end
-
-        def safe_name(klass)
-          if klass.respond_to?(:identifier)
-            klass.identifier
-          else
-            klass.to_s.gsub('::', '.')
-          end
-        end
-
-        def primitive?(value)
-          primitive_def(value) != nil
-        end
-
-        def primitive_def(value)
-          value = value.primitive if value.is_a?(Dry::Types::Nominal)
-
-          return nil unless value.is_a?(Class)
-
-          if (name = primitive_name(value))
-            { type: name }
-          elsif value == Date
-            { type: 'string', format: 'date' }
-          elsif [Time, DateTime].any?(&value.ancestors.method(:include?))
-            { type: 'string', format: 'date-time' }
-          end
-        end
-
-        def primitive_name(value)
-          return 'null' if value == NilClass
-          return 'integer' if value == Integer
-          return 'number' if value == Float
-          return 'string' if value == String
-          return 'boolean' if [TrueClass, FalseClass].include?(value)
-        end
-      end
-
       class TooComplicatedError < ::SoberSwag::Compiler::Error; end
       class TooComplicatedForPathError < TooComplicatedError; end
       class TooComplicatedForQueryError < TooComplicatedError; end
@@ -65,7 +25,15 @@ module SoberSwag
 
       def object_schema
         @object_schema ||=
-          normalize(parsed_type).cata(&method(:to_object_schema))
+          make_object_schema
+      end
+
+      def object_schema_meta
+        return {} unless standalone? && type <= SoberSwag::Type::Named
+
+        {
+          description: type.description
+        }.reject { |_, v| v.nil? }
       end
 
       def schema_stub
@@ -81,14 +49,16 @@ module SoberSwag
         raise TooComplicatedForPathError, e.message
       end
 
+      DEFAULT_QUERY_SCHEMA_ATTRS = { in: :query, style: :deepObject, explode: true }.freeze
+
       def query_schema
-        path_schema_stub.map { |e| e.merge(in: :query, style: :deepObject, explode: true) }
+        path_schema_stub.map { |e| DEFAULT_QUERY_SCHEMA_ATTRS.merge(e) }
       rescue TooComplicatedError => e
         raise TooComplicatedForQueryError, e.message
       end
 
       def ref_name
-        self.class.safe_name(type)
+        SoberSwag::Compiler::Primitive.new(type).ref_name
       end
 
       def found_types
@@ -99,6 +69,10 @@ module SoberSwag
           end
       end
 
+      def mapped_type
+        @mapped_type ||= parsed_type.map { |v| SoberSwag::Compiler::Primitive.new(v).type_hash }
+      end
+
       def parsed_type
         @parsed_type ||=
           begin
@@ -121,22 +95,11 @@ module SoberSwag
 
       private
 
-      def generate_schema_stub # rubocop:disable Metrics/MethodLength
-        return self.class.primitive_def(type) if self.class.primitive?(type)
-
-        case type
-        when Class
-          # refs have to be standalone
-          # so to not interefere with our other stuff, do this horrible garbage
-          { oneOf: [{ '$ref'.to_sym => self.class.get_ref(type) }] }
-        when Dry::Types::Constrained
-          self.class.new(type.type).schema_stub
-        when Dry::Types::Array::Member
-          { type: :array, items: self.class.new(type.member).schema_stub }
-        when Dry::Types::Sum
-          { oneOf: normalize(parsed_type).elements.map { |t| self.class.new(t.value).schema_stub } }
+      def generate_schema_stub
+        if type.is_a?(Class)
+          SoberSwag::Compiler::Primitive.new(type).type_hash
         else
-          raise SoberSwag::Compiler::Error, "Cannot generate a schema stub for #{type} (#{type.class})"
+          object_schema
         end
       end
 
@@ -149,6 +112,10 @@ module SoberSwag
         end
       end
 
+      def make_object_schema(metadata_keys: METADATA_KEYS)
+        normalize(mapped_type).cata { |e| to_object_schema(e, metadata_keys) }.merge(object_schema_meta)
+      end
+
       def normalize(object)
         object.cata { |e| rewrite_sums(e) }.cata { |e| flatten_one_ofs(e) }
       end
@@ -180,29 +147,14 @@ module SoberSwag
         end
       end
 
-      def to_object_schema(object) # rubocop:disable Metrics/MethodLength, Metrics/CyclomaticComplexity
+      def to_object_schema(object, metadata_keys = METADATA_KEYS) # rubocop:disable Metrics/MethodLength, Metrics/CyclomaticComplexity
         case object
         when Nodes::List
-          {
-            type: :array,
-            items: object.deconstruct.first
-          }
+          { type: :array, items: object.element }
         when Nodes::Enum
-          {
-            type: :string,
-            enum: object.deconstruct.first
-          }
+          { type: :string, enum: object.values }
         when Nodes::OneOf
-          if object.deconstruct.include?({ type: 'null' })
-            rejected = object.deconstruct.reject { |e| e[:type] == 'null' }
-            if rejected.length == 1
-              rejected.first.merge(nullable: true)
-            else
-              { oneOf: rejected, nullable: true }
-            end
-          else
-            { oneOf: object.deconstruct }
-          end
+          one_of_to_schema(object)
         when Nodes::Object
           # openAPI requires that you give a list of required attributes
           # (which IMO is the *totally* wrong thing to do but whatever)
@@ -216,41 +168,50 @@ module SoberSwag
             required: required
           }
         when Nodes::Attribute
-          name, req, value = object.deconstruct
+          name, req, value, meta = object.deconstruct
+          value = value.merge(meta&.select { |k, _| metadata_keys.include?(k) } || {})
           if req
             [name, value.merge(required: true)]
           else
             [name, value]
           end
         when Nodes::Primitive
-          value = object.value
-          metadata = object.metadata
-          type_def =
-            if self.class.primitive?(value)
-              self.class.primitive_def(value)
-            else
-              metadata.merge!(value.meta)
-              # refs have to be on their own, this is the stupid workaround
-              # so you can add descriptions and stuff
-              { oneOf: [{ '$ref'.to_sym => self.class.get_ref(value) }] }
-            end
-          METADATA_KEYS.select(&metadata.method(:key?)).reduce(type_def) do |definition, key|
-            definition.merge(key => metadata[key])
-          end
+          object.value.merge(object.metadata.select { |k, _| metadata_keys.include?(k) })
         else
           raise ArgumentError, "Got confusing node #{object} (#{object.class})"
         end
       end
 
+      def one_of_to_schema(object)
+        if object.deconstruct.include?({ type: :null })
+          rejected = object.deconstruct.reject { |e| e[:type] == :null }
+          if rejected.length == 1
+            rejected.first.merge(nullable: true)
+          else
+            { oneOf: flatten_oneofs_hash(rejected), nullable: true }
+          end
+        else
+          { oneOf: flatten_oneofs_hash(object.deconstruct) }
+        end
+      end
+
+      def flatten_oneofs_hash(object)
+        object.map { |h|
+          h[:oneOf] || h
+        }.flatten
+      end
+
       def path_schema_stub
         @path_schema_stub ||=
-          object_schema[:properties].map do |k, v|
+          make_object_schema(metadata_keys: METADATA_KEYS | %i[style explode])[:properties].map do |k, v|
             # ensure_uncomplicated(k, v)
             {
               name: k,
-              schema: v.reject { |key, _| %i[required nullable].include?(key) },
-              required: object_schema[:required].include?(k) || false
-            }
+              schema: v.reject { |key, _| %i[required nullable explode style].include?(key) },
+              required: object_schema[:required].include?(k) || false,
+              style: v[:style],
+              explode: v[:explode]
+            }.reject { |_, v2| v2.nil? }
           end
       end