sober_swag 0.1.0 → 0.2.0

data/example/spec/requests/people/get_spec.rb

@@ -0,0 +1,35 @@
+require 'rails_helper'
+
+RSpec.describe 'Getting a person' do
+  context 'with a good id' do
+    let!(:person) { Person.create(first_name: 'Anthony', last_name: 'Guy') }
+    let(:request) { get "/people/#{person.id}" }
+
+    describe 'the response' do
+      subject { request && response }
+
+      it { should be_successful }
+      it { should_not be_server_error }
+    end
+
+    describe 'the response body' do
+      subject { request && response && JSON.parse(response.body) }
+
+      it { should include('first_name' => 'Anthony') }
+      it { should include('last_name' => 'Guy') }
+    end
+  end
+
+  context 'with a bad id' do
+    let(:request) { get '/people/my-awesome-guy' }
+
+    describe 'the response' do
+      subject { request && response }
+
+      it { should_not be_successful }
+      it { should_not be_server_error }
+      it { should have_http_status(:bad_request) }
+      it { should be_bad_request }
+    end
+  end
+end

data/example/spec/requests/people/index_spec.rb

@@ -0,0 +1,69 @@
+require 'rails_helper'
+
+RSpec.describe 'Index action for people' do
+  let(:parsed_body) { request && response && JSON.parse(response.body) }
+
+  context 'with no people' do
+    let(:request) { get '/people' }
+
+    it 'is successful' do
+      request
+      expect(response).to be_successful
+    end
+
+    it 'is has a blank body' do
+      expect(parsed_body).to be_blank
+    end
+  end
+
+  context 'with a person' do
+    let!(:person) { Person.create(first_name: 'Anthony', last_name: 'Guy') }
+
+    shared_examples 'a request with the person' do
+      it 'is successful' do
+        request
+        expect(response).to be_successful
+      end
+
+      it 'has people' do
+        expect(parsed_body).not_to be_blank
+      end
+
+      it 'has the right person' do
+        expect(parsed_body).to include(include('id' => person.id))
+      end
+    end
+
+    context 'with a good first-name search' do
+      let(:request) { get '/people', params: { first_name: 'A' } }
+
+      it_behaves_like 'a request with the person'
+    end
+
+    context 'with a good last-name search' do
+      let(:request) { get '/people', params: { last_name: 'G' } }
+
+      it_behaves_like 'a request with the person'
+    end
+
+    context 'with a valid view' do
+      let(:request) { get '/people', params: { view: 'detail' } }
+
+      it_behaves_like 'a request with the person'
+    end
+
+    context 'with an invalid view' do
+      let(:request) { get '/people', params: { view: 'not-a-thing-lol' } }
+
+      it 'is not successful' do
+        request
+        expect(response).not_to be_successful
+      end
+
+      it 'is a bad request' do
+        request
+        expect(response).to be_bad_request
+      end
+    end
+  end
+end

data/example/spec/spec_helper.rb

@@ -0,0 +1,94 @@
+# This file was generated by the `rails generate rspec:install` command. Conventionally, all
+# specs live under a `spec` directory, which RSpec adds to the `$LOAD_PATH`.
+# The generated `.rspec` file contains `--require spec_helper` which will cause
+# this file to always be loaded, without a need to explicitly require it in any
+# files.
+#
+# Given that it is always loaded, you are encouraged to keep this file as
+# light-weight as possible. Requiring heavyweight dependencies from this file
+# will add to the boot time of your test suite on EVERY test run, even for an
+# individual file that may not need all of that loaded. Instead, consider making
+# a separate helper file that requires the additional dependencies and performs
+# the additional setup, and require it from the spec files that actually need
+# it.
+#
+# See http://rubydoc.info/gems/rspec-core/RSpec/Core/Configuration
+RSpec.configure do |config|
+  # rspec-expectations config goes here. You can use an alternate
+  # assertion/expectation library such as wrong or the stdlib/minitest
+  # assertions if you prefer.
+  config.expect_with :rspec do |expectations|
+    # This option will default to `true` in RSpec 4. It makes the `description`
+    # and `failure_message` of custom matchers include text for helper methods
+    # defined using `chain`, e.g.:
+    #     be_bigger_than(2).and_smaller_than(4).description
+    #     # => "be bigger than 2 and smaller than 4"
+    # ...rather than:
+    #     # => "be bigger than 2"
+    expectations.include_chain_clauses_in_custom_matcher_descriptions = true
+  end
+
+  # rspec-mocks config goes here. You can use an alternate test double
+  # library (such as bogus or mocha) by changing the `mock_with` option here.
+  config.mock_with :rspec do |mocks|
+    # Prevents you from mocking or stubbing a method that does not exist on
+    # a real object. This is generally recommended, and will default to
+    # `true` in RSpec 4.
+    mocks.verify_partial_doubles = true
+  end
+
+  # This option will default to `:apply_to_host_groups` in RSpec 4 (and will
+  # have no way to turn it off -- the option exists only for backwards
+  # compatibility in RSpec 3). It causes shared context metadata to be
+  # inherited by the metadata hash of host groups and examples, rather than
+  # triggering implicit auto-inclusion in groups with matching metadata.
+  config.shared_context_metadata_behavior = :apply_to_host_groups
+
+  # The settings below are suggested to provide a good initial experience
+  # with RSpec, but feel free to customize to your heart's content.
+  #   # This allows you to limit a spec run to individual examples or groups
+  #   # you care about by tagging them with `:focus` metadata. When nothing
+  #   # is tagged with `:focus`, all examples get run. RSpec also provides
+  #   # aliases for `it`, `describe`, and `context` that include `:focus`
+  #   # metadata: `fit`, `fdescribe` and `fcontext`, respectively.
+  #   config.filter_run_when_matching :focus
+  #
+  #   # Allows RSpec to persist some state between runs in order to support
+  #   # the `--only-failures` and `--next-failure` CLI options. We recommend
+  #   # you configure your source control system to ignore this file.
+  #   config.example_status_persistence_file_path = "spec/examples.txt"
+  #
+  #   # Limits the available syntax to the non-monkey patched syntax that is
+  #   # recommended. For more details, see:
+  #   #   - http://rspec.info/blog/2012/06/rspecs-new-expectation-syntax/
+  #   #   - http://www.teaisaweso.me/blog/2013/05/27/rspecs-new-message-expectation-syntax/
+  #   #   - http://rspec.info/blog/2014/05/notable-changes-in-rspec-3/#zero-monkey-patching-mode
+  #   config.disable_monkey_patching!
+  #
+  #   # Many RSpec users commonly either run the entire suite or an individual
+  #   # file, and it's useful to allow more verbose output when running an
+  #   # individual spec file.
+  #   if config.files_to_run.one?
+  #     # Use the documentation formatter for detailed output,
+  #     # unless a formatter has already been configured
+  #     # (e.g. via a command-line flag).
+  #     config.default_formatter = "doc"
+  #   end
+  #
+  #   # Print the 10 slowest examples and example groups at the
+  #   # end of the spec run, to help surface which specs are running
+  #   # particularly slow.
+  #   config.profile_examples = 10
+  #
+  #   # Run specs in random order to surface order dependencies. If you find an
+  #   # order dependency and want to debug it, you can fix the order by providing
+  #   # the seed, which is printed after each run.
+  #   #     --seed 1234
+  #   config.order = :random
+  #
+  #   # Seed global randomization in this process using the `--seed` CLI option.
+  #   # Setting this allows you to use `--seed` to deterministically reproduce
+  #   # test failures related to randomization by passing the same `--seed` value
+  #   # as the one that triggered the failure.
+  #   Kernel.srand config.seed
+end

data/lib/sober_swag.rb

@@ -15,15 +15,18 @@ module SoberSwag
 
   autoload :Parser, 'sober_swag/parser'
   autoload :Serializer, 'sober_swag/serializer'
-  autoload :Blueprint, 'sober_swag/blueprint'
+  autoload :OutputObject, 'sober_swag/output_object'
   autoload :Nodes, 'sober_swag/nodes'
   autoload :Compiler, 'sober_swag/compiler'
   autoload :Controller, 'sober_swag/controller'
+  autoload :InputObject, 'sober_swag/input_object'
+  autoload :Server, 'sober_swag/server'
 
   ##
   # Define a struct of something.
   # Useful to prevent weirdness from autoloading.
-  def self.struct(parent = Dry::Struct, &block)
-    Class.new(parent, &block)
+  # @param parent [Class] the base class for the struct (default of {SoberSwag::Struct})
+  def self.input_object(parent = nil, &block)
+    Class.new(parent || SoberSwag::InputObject, &block)
   end
 end

data/lib/sober_swag/compiler/error.rb

@@ -1,5 +1,7 @@
 module SoberSwag
   class Compiler
+    ##
+    # Base class of compilation errors.
     class Error < ::SoberSwag::Error; end
   end
 end

data/lib/sober_swag/compiler/path.rb

@@ -24,7 +24,7 @@ module SoberSwag
         base
       end
 
-      def responses
+      def responses # rubocop:disable Metrics/MethodLength
         route.response_serializers.map { |status, serializer|
           [
             status.to_s,
@@ -32,9 +32,7 @@ module SoberSwag
               description: route.response_descriptions[status],
               content: {
                 'application/json': {
-                  schema: compiler.response_for(
-                    serializer.respond_to?(:new) ? serializer.new.type : serializer.type
-                  )
+                  schema: compiler.response_for(serializer.type)
                 }
               }
             }
@@ -74,7 +72,6 @@ module SoberSwag
           }
         }
       end
-
     end
   end
 end

data/lib/sober_swag/compiler/paths.rb

@@ -48,7 +48,6 @@ module SoberSwag
       def compile_route(route, compiler)
         SoberSwag::Compiler::Path.new(route, compiler).schema
       end
-
     end
   end
 end

data/lib/sober_swag/compiler/type.rb

@@ -3,14 +3,18 @@ module SoberSwag
     ##
     # A compiler for DRY-Struct data types, essentially.
     # It only consumes one type at a time.
-    class Type
+    class Type # rubocop:disable Metrics/ClassLength
       class << self
         def get_ref(klass)
           "#/components/schemas/#{safe_name(klass)}"
         end
 
         def safe_name(klass)
-          klass.to_s.gsub('::', '.')
+          if klass.respond_to?(:identifier)
+            klass.identifier
+          else
+            klass.to_s.gsub('::', '.')
+          end
         end
 
         def primitive?(value)
@@ -42,6 +46,8 @@ module SoberSwag
       class TooComplicatedForPathError < TooComplicatedError; end
       class TooComplicatedForQueryError < TooComplicatedError; end
 
+      METADATA_KEYS = %i[description deprecated].freeze
+
       def initialize(type)
         @type = type
       end
@@ -91,7 +97,7 @@ module SoberSwag
       def parsed_type
         @parsed_type ||=
           begin
-            (parsed, _)  = parsed_result
+            (parsed,) = parsed_result
             parsed
           end
       end
@@ -110,7 +116,7 @@ module SoberSwag
 
       private
 
-      def generate_schema_stub
+      def generate_schema_stub # rubocop:disable Metrics/MethodLength
         return self.class.primitive_def(type) if self.class.primitive?(type)
 
         case type
@@ -120,6 +126,8 @@ module SoberSwag
           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 } }
         else
           raise ArgumentError, "Cannot generate a schema stub for #{type} (#{type.class})"
         end
@@ -138,7 +146,7 @@ module SoberSwag
         object.cata { |e| rewrite_sums(e) }.cata { |e| flatten_one_ofs(e) }
       end
 
-      def rewrite_sums(object)
+      def rewrite_sums(object) # rubocop:disable Metrics/MethodLength
         case object
         in Nodes::Sum[Nodes::OneOf[*lhs], Nodes::OneOf[*rhs]]
         Nodes::OneOf.new(lhs + rhs)
@@ -157,12 +165,12 @@ module SoberSwag
         case object
           in Nodes::OneOf[*args]
           Nodes::OneOf.new(args.uniq)
-        else
+          else
           object
         end
       end
 
-      def to_object_schema(object)
+      def to_object_schema(object) # rubocop:disable Metrics/MethodLength, Metrics/CyclomaticComplexity
         case object
         in Nodes::List[element]
           {
@@ -186,11 +194,11 @@ module SoberSwag
         # openAPI requires that you give a list of required attributes
         # (which IMO is the *totally* wrong thing to do but whatever)
         # so we must do this garbage
-        required = attrs.filter {|(_, b)| b[:required] }.map(&:first)
+        required = attrs.filter { |(_, b)| b[:required] }.map(&:first)
         {
           type: :object,
-          properties: attrs.map { |(a,b)|
-            [a, b.select { |k, _| k != :required }]
+          properties: attrs.map { |(a, b)|
+            [a, b.reject { |k, _| k == :required }]
           }.to_h,
           required: required
         }
@@ -201,8 +209,11 @@ module SoberSwag
         # can't match on value directly as ruby uses `===` to match,
         # and classes use `===` to mean `is an instance of`, as
         # opposed to direct equality lmao
-        in Nodes::Primitive[value:] if self.class.primitive?(value)
-        self.class.primitive_def(value)
+        in Nodes::Primitive[value:, metadata:] if self.class.primitive?(value)
+        md = self.class.primitive_def(value)
+        METADATA_KEYS.select(&metadata.method(:key?)).reduce(md) do |definition, key|
+          definition.merge(key => metadata[key])
+        end
         in Nodes::Primitive[value:]
         { '$ref': self.class.get_ref(value) }
         else
@@ -216,20 +227,22 @@ module SoberSwag
             ensure_uncomplicated(k, v)
             {
               name: k,
-              schema: v.reject { |k, _| %i[required nullable].include?(k) },
+              schema: v.reject { |key, _| %i[required nullable].include?(key) },
+              # rubocop:disable Style/DoubleNegation
               allowEmptyValue: !object_schema[:required].include?(k) || !!v[:nullable], # if it's required, no empties, but if *nullabe*, empties are okay
-              required: object_schema[:required].include?(k) || false,
+              # rubocop:enable Style/DoubleNegation
+              required: object_schema[:required].include?(k) || false
             }
           end
       end
 
       def ensure_uncomplicated(key, value)
         return if value[:type]
+
         raise TooComplicatedError, <<~ERROR
           Property #{key} has object-schema #{value}, but this type of param should be simple (IE a primitive of some kind)
         ERROR
       end
-
     end
   end
 end

data/lib/sober_swag/controller.rb

@@ -10,10 +10,19 @@ module SoberSwag
     autoload :UndefinedPathError, 'sober_swag/controller/undefined_path_error'
     autoload :UndefinedQueryError, 'sober_swag/controller/undefined_query_error'
 
+    ##
+    # Types module, so you can more easily access Types::Whatever
+    # without having to type SoberSwag::Types::Whatever.
     module Types
       include ::Dry::Types()
     end
 
+    included do
+      rescue_from Dry::Struct::Error do
+        head :bad_request
+      end
+    end
+
     class_methods do
       ##
       # Define a new action with the given HTTP method, action name, and path.
@@ -65,10 +74,7 @@ module SoberSwag
             res = defined_routes.reduce(SoberSwag::Compiler.new) { |c, r| c.add_route(r) }
             {
               openapi: '3.0.0',
-              info: {
-                version: '1',
-                title: self.name
-              }
+              info: { version: '1', title: name }
             }.merge(res.to_swagger)
           end
       end
@@ -89,6 +95,7 @@ module SoberSwag
         begin
           r = current_action_def
           raise UndefinedPathError unless r&.path_params_class
+
           r.path_params_class.new(request.path_parameters)
         end
     end
@@ -102,6 +109,7 @@ module SoberSwag
         begin
           r = current_action_def
           raise UndefinedBodyError unless r&.request_body_class
+
           r.request_body_class.new(body_params)
         end
     end
@@ -115,6 +123,7 @@ module SoberSwag
         begin
           r = current_action_def
           raise UndefinedQueryError unless r&.query_params_class
+
           r.query_params_class.new(request.query_parameters)
         end
     end
@@ -124,11 +133,11 @@ module SoberSwag
     # @todo figure out how to specify views and other options for the serializer here
     # @param status [Symbol] the HTTP status symbol to use for the status code
     # @param entity the thing to serialize
-    def respond!(status, entity)
+    def respond!(status, entity, serializer_opts: {}, rails_opts: {})
       r = current_action_def
       serializer = r.response_serializers[Rack::Utils.status_code(status)]
       serializer ||= serializer.new if serializer.respond_to?(:new)
-      render json: serializer.serialize(entity)
+      render json: serializer.serialize(entity, serializer_opts), status: status, **rails_opts
     end
 
     ##
@@ -138,10 +147,7 @@ module SoberSwag
     # but it keeps the docs honest: parameters sent in the body *must* be
     # in the body.
     def body_params
-      bparams = params.reject do |k, _|
-        request.query_parameters.key?(k) || request.path_parameters.key?(k)
-      end
-      bparams.permit(bparams.keys)
+      request.request_parameters
     end
 
     ##
@@ -150,7 +156,6 @@ module SoberSwag
     def current_action_def
       self.class.find_route(params[:action])
     end
-
   end
 end