apiculture 0.1.6 → 0.2.0

data/lib/apiculture.rb

@@ -9,40 +9,41 @@ module Apiculture
   require_relative 'apiculture/markdown_segment'
   require_relative 'apiculture/timestamp_promise'
   require_relative 'apiculture/app_documentation'
-  
+  require_relative 'apiculture/openapi_documentation'
+
   def self.extended(in_class)
     in_class.send(:include, SinatraInstanceMethods)
     super
   end
-  
+
   IDENTITY_PROC = ->(arg) { arg }
-  
+
   AC_APPLY_TYPECAST_PROC = ->(cast_proc_or_method, v) {
     cast_proc_or_method.is_a?(Symbol) ? v.public_send(cast_proc_or_method) : cast_proc_or_method.call(v)
   }
-  
+
   AC_CHECK_PRESENCE_PROC = ->(name_as_string, params) {
     params.has_key?(name_as_string) or raise MissingParameter.new(name_as_string)
   }
-  
+
   AC_CHECK_TYPE_PROC = ->(param, value) {
     param.matchable === value or raise ParameterTypeMismatch.new(param, value.class)
   }
-  
+
   class Parameter < Struct.new(:name, :description, :required, :matchable, :cast_proc_or_method)
     # Return Strings since Sinatra prefers string keys for params{}
     def name_as_string; name.to_s; end
   end
-  
+
   class RouteParameter < Parameter
   end
-  
+
   class PossibleResponse < Struct.new(:http_status_code, :description, :jsonable_object_example)
     def no_body?
       jsonable_object_example.nil?
     end
   end
-  
+
   # Indicates where this API will be mounted. This is only used
   # for the generated documentation. In general, this should match
   # the SCRIPT_NAME of the Sinatra application when it will be called.
@@ -60,13 +61,13 @@ module Apiculture
   def mounted_at(path)
     @apiculture_mounted_at = path.to_s.gsub(/\/$/, '')
   end
-  
+
   # Inserts the generation timestamp into the documentation at this point.
   # The timestamp will be not very precise (to the minute) and in UTC time
   def documentation_build_time!
     apiculture_stack << Apiculture::TimestampPromise
   end
-  
+
   # Inserts a literal Markdown string into the documentation at this point.
   # For instance, if used after an API method declaration, it will insert
   # the header between the API methods in the doc.
@@ -81,7 +82,7 @@ module Apiculture
   def markdown_string(str)
     apiculture_stack << MarkdownSegment.new(str)
   end
-  
+
   # Inserts the contents of the file at +path+ into the documentation, using +markdown_string+.
   # For instance, if used after an API method declaration, it will insert
   # the header between the API methods in the doc.
@@ -94,25 +95,25 @@ module Apiculture
     md = File.read(path_to_markdown).encode(Encoding::UTF_8)
     markdown_string(md)
   end
-  
+
   # Describe the API method that is going to be defined
   def desc(action_description)
     @apiculture_action_definition ||= ActionDefinition.new
     @apiculture_action_definition.description = action_description.to_s
   end
-  
+
   # Add an optional parameter for the API call
   def param(name, description, matchable, cast: IDENTITY_PROC)
     @apiculture_action_definition ||= ActionDefinition.new
     @apiculture_action_definition.parameters << Parameter.new(name, description, required=false, matchable, cast)
   end
-  
+
   # Add a requred parameter for the API call
   def required_param(name, description, matchable, cast: IDENTITY_PROC)
     @apiculture_action_definition ||= ActionDefinition.new
     @apiculture_action_definition.parameters << Parameter.new(name, description, required=true, matchable, cast)
   end
-  
+
   # Describe a parameter that has to be included in the URL of the API call.
   # Route parameters are always required, and all the parameters specified
   # using +route_param+ should also be included in the path given for the route
@@ -121,28 +122,28 @@ module Apiculture
     @apiculture_action_definition ||= ActionDefinition.new
     @apiculture_action_definition.route_parameters << RouteParameter.new(name, description, required=false, matchable, cast)
   end
-  
+
   # Add a possible response, specifying the code and the JSON Response by example.
   # Multiple response packages can be specified.
   def responds_with(http_status, description, example_jsonable_object = nil)
     @apiculture_action_definition ||= ActionDefinition.new
     @apiculture_action_definition.responses << PossibleResponse.new(http_status, description, example_jsonable_object)
   end
-  
+
   DefinitionError = Class.new(StandardError)
   ValidationError = Class.new(StandardError)
-  
+
   class RouteParameterNotInPath < DefinitionError; end
   class ReservedParameter < DefinitionError; end
   class ConflictingParameter < DefinitionError; end
-  
+
   # Gets raised when a parameter is missing
   class MissingParameter < ValidationError
     def initialize(parameter_name)
       super "Missing parameter :#{parameter_name}"
     end
   end
-  
+
   # Gets raised when a parameter is supplied and has a wrong type
   class ParameterTypeMismatch < ValidationError
     def initialize(ac_parameter, received_ruby_type)
@@ -151,7 +152,7 @@ module Apiculture
       super "Received #{received_type}, expected #{expected_type.inspect} for :#{parameter_name}"
     end
   end
-  
+
   # Returns a Proc that calls the strong parameters to check the presence/types
   def parametric_validator_proc_from(parametric_validators, implicitly_defined_route_parameter_names)
     required_params = parametric_validators.select{|e| e.required }
@@ -163,23 +164,23 @@ module Apiculture
       parametric_validators.each do |param|
         param_name = param.name_as_string
         next unless params.has_key?(param_name) # this is checked via required_params
-        
+
         # Apply the type cast and save it (since using our override we can mutate the params)
         value_after_type_cast = AC_APPLY_TYPECAST_PROC.call(param.cast_proc_or_method, params[param_name])
         params[param_name] = value_after_type_cast
-        
+
         # Ensure the typecast value adheres to the enforced Ruby type
         AC_CHECK_TYPE_PROC.call(param, params[param_name])
       end
-      
-      # The following only applies if the app does not use strong_parameters - 
+
+      # The following only applies if the app does not use strong_parameters -
       # this makes use of parameter mutability again to kill the parameters that are not permitted
       # or mentioned in the API specification. We need to keep the params which are specified in the
       # route but not documented via Apiculture though
       unexpected_parameters = Set.new(params.keys.map(&:to_s)) -
         Set.new(parametric_validators.map(&:name).map(&:to_s)) -
         Set.new(implicitly_defined_route_parameter_names.map(&:to_s))
-      
+
       unexpected_parameters.each do | parameter_to_discard |
         # TODO: raise or record a warning
         if env['rack.logger'].respond_to?(:warn)
@@ -189,7 +190,7 @@ module Apiculture
       end
     }
   end
-  
+
   # Serve the documentation for the API at the given URL
   def serve_api_documentation_at(url)
     get(url) do
@@ -197,7 +198,7 @@ module Apiculture
       self.class.api_documentation.to_html
     end
   end
-  
+
   # Returns an +AppDocumentation+ object for all actions defined so far.
   #
   #   MyApi.api_documentation.to_markdown #=> "..."
@@ -205,14 +206,14 @@ module Apiculture
   def api_documentation
     AppDocumentation.new(self, @apiculture_mounted_at.to_s, @apiculture_actions_and_docs || [])
   end
-  
+
   # Define an API method. Under the hood will call the related methods in Sinatra
   # to define the route.
   def api_method(http_verb, path, options={}, &blk)
     action_def = (@apiculture_action_definition || ActionDefinition.new)
     action_def.http_verb = http_verb
     action_def.path = path
-    
+
     # Ensure no reserved Sinatra parameters are used
     all_parameter_names = action_def.all_parameter_names_as_strings
     %w( splat captures ).each do | reserved_param |
@@ -220,34 +221,34 @@ module Apiculture
         raise ReservedParameter.new(":#{reserved_param} is a reserved magic parameter name in Sinatra")
       end
     end
-    
+
     # Ensure no conflations between route/req params
     seen_params = {}
-    all_parameter_names.each do |e| 
+    all_parameter_names.each do |e|
       if seen_params[e]
-        raise ConflictingParameter.new(":#{e} mentioned twice as a possible parameter. Note that URL" + 
+        raise ConflictingParameter.new(":#{e} mentioned twice as a possible parameter. Note that URL" +
           " parameters and request parameters share a namespace.")
       else
         seen_params[e] = true
       end
     end
-    
+
     # Ensure the path has the route parameters that were predeclared
     action_def.route_parameters.map(&:name).each do | route_parameter_key |
       unless path.include?(':%s' % route_parameter_key)
         raise RouteParameterNotInPath.new("Parameter :#{route_parameter_key} not present in path #{path.inspect}")
       end
     end
-    
+
     # TODO: ensure all route parameters are documented
-    
+
     # Pick out all the defined parameters and set up a block that can validate them
     # when the action is called. With that, set up the actual Sinatra method that will
     # respond to the request. We take care to preserve all the params that have NOT been documented
     # using Apiculture but _were_ in fact specified in the actual path.
     route_parameter_names = path.scan(/:([^:\/]+)/).flatten.map(&:to_sym)
     parametric_checker_proc = parametric_validator_proc_from(action_def.parameters + action_def.route_parameters, route_parameter_names)
-    public_send(http_verb, path, options) do |*matched_sinatra_route_params|
+    public_send(http_verb, path, **options) do |*matched_sinatra_route_params|
       # Extract all the parameter names from the route path as given to the method
       route_parameters = Hash[route_parameter_names.zip(matched_sinatra_route_params)]
 
@@ -268,13 +269,13 @@ module Apiculture
       # Execute the original action via instance_exec, passing along the route args
       instance_exec(*route_parameters.values, &blk)
     end
-    
+
     # Reset for the subsequent action definition
     @apiculture_action_definition = ActionDefinition.new
     # and store the just defined action for future use
     apiculture_stack << action_def
   end
-  
+
   def apiculture_stack
     @apiculture_actions_and_docs ||= []
     @apiculture_actions_and_docs

metadata

@@ -1,32 +1,32 @@
 --- !ruby/object:Gem::Specification
 name: apiculture
 version: !ruby/object:Gem::Version
-  version: 0.1.6
+  version: 0.2.0
 platform: ruby
 authors:
 - Julik Tarkhanov
 - WeTransfer
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2021-01-27 00:00:00.000000000 Z
+date: 2023-02-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
-  name: mustermann
+  name: builder
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1'
+        version: '3'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1'
+        version: '3'
 - !ruby/object:Gem::Dependency
-  name: builder
+  name: github-markup
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
@@ -40,21 +40,21 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '3'
 - !ruby/object:Gem::Dependency
-  name: rdiscount
+  name: mustache
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2'
+        version: '1'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2'
+        version: '1'
 - !ruby/object:Gem::Dependency
-  name: github-markup
+  name: mustermann
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
@@ -68,61 +68,61 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '3'
 - !ruby/object:Gem::Dependency
-  name: mustache
+  name: rdiscount
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1'
+        version: '2'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1'
+        version: '2'
 - !ruby/object:Gem::Dependency
-  name: rack-test
+  name: bundler
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '2.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '2.0'
 - !ruby/object:Gem::Dependency
-  name: rspec
+  name: cgi
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '3'
+        version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '3'
+        version: '0'
 - !ruby/object:Gem::Dependency
-  name: rdoc
+  name: rack-test
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '6.0'
+        version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '6.0'
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -138,33 +138,33 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: bundler
+  name: rdoc
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.0'
+        version: '6.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.0'
+        version: '6.0'
 - !ruby/object:Gem::Dependency
-  name: simplecov
+  name: rspec
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '3'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '3'
 description: A toolkit for building REST APIs on top of Rack
 email: me@julik.nl
 executables: []
@@ -175,6 +175,7 @@ extra_rdoc_files:
 files:
 - ".gitignore"
 - ".travis.yml"
+- CHANGELOG.md
 - Gemfile
 - LICENSE.txt
 - README.md
@@ -191,20 +192,16 @@ files:
 - lib/apiculture/indifferent_hash.rb
 - lib/apiculture/markdown_segment.rb
 - lib/apiculture/method_documentation.rb
+- lib/apiculture/openapi_documentation.rb
 - lib/apiculture/sinatra_instance_methods.rb
 - lib/apiculture/timestamp_promise.rb
 - lib/apiculture/version.rb
-- spec/apiculture/action_spec.rb
-- spec/apiculture/app_documentation_spec.rb
-- spec/apiculture/method_documentation_spec.rb
-- spec/apiculture_spec.rb
-- spec/spec_helper.rb
 homepage: https://github.com/WeTransfer/apiculture
 licenses:
 - MIT
 metadata:
   allowed_push_host: https://rubygems.org
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -219,8 +216,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.3
-signing_key: 
+rubygems_version: 3.2.33
+signing_key:
 specification_version: 4
 summary: Sweet API sauce on top of Rack
 test_files: []

data/spec/apiculture/action_spec.rb

@@ -1,45 +0,0 @@
-require_relative '../spec_helper'
-
-describe Apiculture::Action do
-  context '.new' do
-    it 'exposes the methods of the object given as a first argument to initialize' do
-      action_class = Class.new(described_class)
-      fake_app = double('Apiculture::App', something: 'value')
-      action = action_class.new(fake_app)
-      expect(action).to respond_to(:something)
-      expect(action.something).to eq('value')
-    end
-
-    it 'converts keyword arguments to instance variables' do
-      action_class = Class.new(described_class)
-      action = action_class.new(nil, foo: 'a string')
-      expect(action.instance_variable_get('@foo')).to eq('a string')
-    end
-  end
-
-  it 'responds to perform()' do
-    expect(described_class.new(nil)).to respond_to(:perform)
-  end
-
-  it 'can use bail() to throw a Sinatra halt' do
-    fake_app = double('Apiculture::App')
-    expect(fake_app).to receive(:json_halt).with('Failure', status: 400) 
-    action_class = Class.new(described_class)
-    action_class.new(fake_app).bail "Failure"
-  end
-
-  it 'can use bail() to throw a Sinatra halt with a custom status' do
-    fake_app = double('Apiculture::App')
-    expect(fake_app).to receive(:json_halt).with("Failure", status: 417)
-
-    action_class = Class.new(described_class)
-    action_class.new(fake_app).bail "Failure", status: 417
-  end
-
-  it 'can use bail() to throw a Sinatra halt with extra JSON attributes' do
-    fake_app = double('Apiculture::App')
-    expect(fake_app).to receive(:json_halt).with("Failure", status: 417, message: "Totale")
-    action_class = Class.new(described_class)
-    action_class.new(fake_app).bail "Failure", status: 417, message: 'Totale'
-  end
-end

data/spec/apiculture/app_documentation_spec.rb

@@ -1,126 +0,0 @@
-require_relative '../spec_helper'
-
-describe "Apiculture.api_documentation" do
-  let(:app) do
-    Class.new(Apiculture::App) do
-      extend Apiculture
-
-      markdown_string 'This API is very important. Because it has to do with pancakes.'
-
-      documentation_build_time!
-
-      desc 'Order a pancake'
-      required_param :diameter, "Diameter of the pancake. The pancake will be **bold**", Integer
-      param :topping, 'Type of topping', String
-      pancake_response_info = <<~EOS
-        When the pancake has been baked successfully
-        The pancake will have the following properties:
-
-        * It is going to be round
-        * It is going to be delicious
-      EOS
-      responds_with 200, pancake_response_info, { id: 'abdef..c21' }
-      api_method :post, '/pancakes' do
-      end
-
-      desc 'Check the pancake status'
-      route_param :id, 'Pancake ID to check status on'
-      responds_with 200, 'When the pancake is found', { status: 'Baking' }
-      responds_with 404, 'When no such pancake exists', { status: 'No such pancake' }
-      api_method :get, '/pancake/:id' do
-      end
-
-      desc 'Throw away the pancake'
-      route_param :id, 'Pancake ID to delete'
-      api_method :delete, '/pancake/:id' do
-      end
-
-      desc 'Pancake ingredients are in the URL'
-      route_param :topping_id, 'Pancake topping ID', Integer, cast: :to_i
-      api_method :get, '/pancake/with/:topping_id' do |topping_id|
-      end
-    end
-  end
-
-  it 'generates app documentation as HTML without the body element' do
-    docco = app.api_documentation
-    generated_html = docco.to_html_fragment
-
-    expect(generated_html).not_to include('<body')
-    expect(generated_html).to include('Pancake ID to check status on')
-    expect(generated_html).to include('Pancake ID to delete')
-  end
-
-  it 'generates app documentation in HTML' do
-    docco = app.api_documentation
-    generated_html = docco.to_html
-
-    if ENV['SHOW_TEST_DOC']
-      File.open('t.html', 'w') do |f|
-        f.write(generated_html)
-        f.flush
-        `open #{f.path}`
-      end
-    end
-
-    expect(generated_html).to include('<body')
-    expect(generated_html).to include('Pancake ID to check status on')
-    expect(generated_html).to include('When the pancake has been baked successfully')
-    expect(generated_html).to include('"id": "abdef..c21"')
-    expect(generated_html).to end_with("\n")
-  end
-
-  it 'generates app documentation in Markdown' do
-    docco = app.api_documentation
-    generated_markdown = docco.to_markdown
-
-    expect(generated_markdown).not_to include('<body')
-    expect(generated_markdown).to include('## POST /pancakes')
-  end
-
-  it 'generates app documentation honoring the mount point' do
-    overridden = Class.new(Apiculture::App) do
-      extend Apiculture
-      mounted_at '/api/v2/'
-      api_method :get, '/pancakes' do
-      end
-    end
-
-    generated_markdown = overridden.api_documentation.to_markdown
-    expect(generated_markdown).to include('## GET /api/v2/pancakes')
-  end
-
-  it 'generates app documentation injecting the inline Markdown strings' do
-    app_class = Class.new(Apiculture::App) do
-      extend Apiculture
-      markdown_string '# This describes important stuff'
-      api_method :get, '/pancakes' do
-      end
-      markdown_string '# This describes even more important stuff'
-      markdown_string 'This is a paragraph'
-    end
-
-    generated_html = app_class.api_documentation.to_html
-    expect(generated_html).to include('<h2>GET /pancakes</h2>')
-    expect(generated_html).to include('<h1>This describes even more important stuff')
-    expect(generated_html).to include('<h1>This describes important stuff')
-    expect(generated_html).to include('<p>This is a paragraph')
-  end
-
-  context 'with a file containing Markdown that has to be spliced into the docs' do
-    before(:each) { File.open('./TEST.md', 'w') { |f| f << "# This is an important header" } }
-    after(:each) { File.unlink('./TEST.md') }
-    it 'splices the contents of the file using markdown_file' do
-      app_class = Class.new(Apiculture::App) do
-        extend Apiculture
-        markdown_file './TEST.md'
-        api_method :get, '/pancakes' do
-        end
-      end
-
-      generated_html = app_class.api_documentation.to_html
-      expect(generated_html).to include('<h2>GET /pancakes</h2>')
-      expect(generated_html).to include('<h1>This is an important header')
-    end
-  end
-end