apiculture 0.0.12

data/spec/apiculture/app_documentation_spec.rb

@@ -0,0 +1,113 @@
+require_relative '../spec_helper'
+
+describe "Apiculture.api_documentation" do
+  let(:app) {
+    Class.new(Sinatra::Base) 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", Integer
+      param :topping, 'Type of topping', String
+      responds_with 200, 'When the pancake is created succesfully', {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
+    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 is created succesfully')
+    expect(generated_html).to include('"id": "abdef..c21"')
+  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(Sinatra::Base) 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(Sinatra::Base) 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(Sinatra::Base) 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

data/spec/apiculture/method_documentation_spec.rb

@@ -0,0 +1,80 @@
+require_relative '../spec_helper'
+require_relative '../../lib/apiculture/method_documentation'
+
+describe Apiculture::MethodDocumentation do
+  it 'generates HTML from an ActionDefinition with path, verb and both route and request params' do
+    definition = Apiculture::ActionDefinition.new
+    
+    definition.description = "This action bakes pancakes"
+    definition.parameters << Apiculture::Parameter.new(:name, 'Pancake name', true, String, :to_s)
+    definition.parameters << Apiculture::Parameter.new(:thickness, 'Pancake thickness', false, Float, :to_f)
+    definition.parameters << Apiculture::Parameter.new(:diameter, 'Pancake diameter', false, Integer, :to_i)
+    
+    definition.route_parameters << Apiculture::RouteParameter.new(:pan_id, 'ID of the pancake frying pan')
+    definition.http_verb = 'get'
+    definition.path = '/pancake/:pan_id/bake'
+    
+    documenter = described_class.new(definition)
+    
+    generated_html = documenter.to_html_fragment
+    generated_markdown = documenter.to_markdown
+    
+    expect(generated_html).not_to include('<body>')
+    
+    expect(generated_html).to include('<h2>GET /pancake/:pan_id/bake</h2>')
+    expect(generated_html).to include('<p>This action bakes pancakes</p>')
+    expect(generated_html).to include('<h3>URL parameters</h3>')
+    expect(generated_html).to include('ID of the pancake frying pan')
+    expect(generated_html).to include('<h3>Request parameters</h3>')
+    expect(generated_html).to include('<td>Pancake name</td>')
+  end
+  
+  it 'generates HTML from an ActionDefinition without route params' do
+    definition = Apiculture::ActionDefinition.new
+    
+    definition.description = "This action bakes pancakes"
+    definition.parameters << Apiculture::Parameter.new(:name, 'Pancake name', true, String, :to_s)
+    definition.parameters << Apiculture::Parameter.new(:thickness, 'Pancake thickness', false, Float, :to_f)
+    definition.parameters << Apiculture::Parameter.new(:diameter, 'Pancake diameter', false, Integer, :to_i)
+    
+    definition.http_verb = 'get'
+    definition.path = '/pancake'
+    
+    documenter = described_class.new(definition)
+    generated_html = documenter.to_html_fragment
+    
+    expect(generated_html).not_to include('<h3>URL parameters</h3>')
+  end
+  
+  it 'generates HTML from an ActionDefinition without request params' do
+    definition = Apiculture::ActionDefinition.new
+    
+    definition.description = "This action bakes pancakes"
+    
+    definition.route_parameters << Apiculture::RouteParameter.new(:pan_id, 'ID of the pancake frying pan')
+    definition.http_verb = 'get'
+    definition.path = '/pancake/:pan_id/bake'
+    
+    documenter = described_class.new(definition)
+    
+    generated_html = documenter.to_html_fragment
+    generated_markdown = documenter.to_markdown
+    
+    expect(generated_html).not_to include('<h3>Request parameters</h3>')
+  end
+  
+  it 'generates Markdown from an ActionDefinition with a mountpoint' do
+    definition = Apiculture::ActionDefinition.new
+    
+    definition.description = "This action bakes pancakes"
+    
+    definition.route_parameters << Apiculture::RouteParameter.new(:pan_id, 'ID of the pancake frying pan')
+    definition.http_verb = 'get'
+    definition.path = '/pancake/:pan_id/bake'
+    
+    documenter = described_class.new(definition, '/api/v1')
+    
+    generated_markdown = documenter.to_markdown
+    expect(generated_markdown).to include('## GET /api/v1/pancake/:pan_id')
+  end
+end

data/spec/apiculture_spec.rb

@@ -0,0 +1,263 @@
+require File.expand_path(File.dirname(__FILE__) + '/spec_helper')
+
+describe "Apiculture" do
+  include Rack::Test::Methods
+  
+  before(:each) { @app_class = nil }
+  def app
+    @app_class or raise "No @app_class defined in the example"
+  end
+  
+  context 'as API definition DSL' do
+    it 'allows all the standard Siantra DSL to go through without modifications' do
+      @app_class = Class.new(Sinatra::Base) do
+        settings.show_exceptions = false
+        settings.raise_errors = true
+        extend Apiculture
+      
+        post '/things/*' do
+          return params.inspect
+        end
+      end
+      
+      post '/things/a/b/c/d', {'foo' => 'bar'}
+      expect(last_response.body).to eq("{\"foo\"=>\"bar\", \"splat\"=>[\"a/b/c/d\"], \"captures\"=>[\"a/b/c/d\"]}")
+    end
+    
+    it 'flags :captures as a reserved Sinatra parameter when used as a URL param' do
+      expect {
+        Class.new(Sinatra::Base) do
+          extend Apiculture
+          route_param :captures, "Something it captures"
+          api_method(:get, '/thing/:captures') { raise "Should never be called" }
+        end
+      }.to raise_error(/\:captures is a reserved magic parameter name/)
+    end
+    
+    it 'flags :captures as a reserved Sinatra parameter when used as a request param' do
+      expect {
+        Class.new(Sinatra::Base) do
+          extend Apiculture
+          param :captures, "Something it captures", String
+          api_method(:get, '/thing') { raise "Should never be called" }
+        end
+      }.to raise_error(/\:captures is a reserved magic parameter name/)
+    end
+    
+    it 'flags :splat as a reserved Sinatra parameter when used as a URL param' do
+      expect {
+        Class.new(Sinatra::Base) do
+          extend Apiculture
+          route_param :splat, "Something it splats"
+          api_method(:get, '/thing/:splat') { raise "Should never be called" }
+        end
+      }.to raise_error(/\:splat is a reserved magic parameter name/)
+    end
+    
+    it 'flags :splat as a reserved Sinatra parameter when used as a request param' do
+      expect {
+        Class.new(Sinatra::Base) do
+          extend Apiculture
+          param :splat, "Something it splats", String
+          api_method(:get, '/thing') { raise "Should never be called" }
+        end
+      }.to raise_error(/\:splat is a reserved magic parameter name/)
+    end
+    
+    it 'flags URL and request params of the same name' do
+      expect {
+        Class.new(Sinatra::Base) do
+          extend Apiculture
+          route_param :id, 'Id of the thing'
+          param :id, "Something it identifies (conflict)", String
+          api_method(:get, '/thing/:id') { raise "Should never be called" }
+        end
+      }.to raise_error(/\:id mentioned twice/)
+    end
+    
+    it "defines a basic API that can be called" do
+      $created_thing = nil
+      @app_class = Class.new(Sinatra::Base) do
+        settings.show_exceptions = false
+        settings.raise_errors = true
+      
+        extend Apiculture
+      
+        desc "Create a Thing with a name"
+        route_param :id, "The ID of the thing"
+        required_param :name, "Name of the thing", String
+        api_method :post, '/thing/:id' do | thing_id |
+          $created_thing = {id: thing_id, name: params[:name]}
+          'Wild success'
+        end
+      end
+    
+      post '/thing/123', {name: 'Monsieur Thing'}
+      expect(last_response.body).to eq('Wild success')
+      expect($created_thing).to eq({id: '123', name: 'Monsieur Thing'})
+    end
+    
+    it "serves the API documentation at a given URL using serve_api_documentation_at" do
+      $created_thing = nil
+      @app_class = Class.new(Sinatra::Base) do
+        settings.show_exceptions = false
+        settings.raise_errors = true
+      
+        extend Apiculture
+      
+        desc "Create a Thing with a name"
+        required_param :name, "Name of the thing", String
+        api_method( :post, '/thing/:id') {}
+        serve_api_documentation_at('/documentation')
+      end
+    
+      get '/documentation'
+      expect(last_response['Content-Type']).to include('text/html')
+      expect(last_response.body).to include('Create a Thing')
+    end
+    
+    it 'raises when a required param is not provided' do
+      @app_class = Class.new(Sinatra::Base) do
+        settings.show_exceptions = false
+        settings.raise_errors = true
+        extend Apiculture
+      
+        required_param :name, "Name of the thing", String
+        api_method :post, '/thing' do
+          raise "Should never be called"
+        end
+      end
+    
+      expect {
+        post '/thing', {}
+      }.to raise_error('Missing parameter :name')
+    end
+  
+    it 'verifies the parameter type' do
+      @app_class = Class.new(Sinatra::Base) do
+        settings.show_exceptions = false
+        settings.raise_errors = true
+        extend Apiculture
+      
+        required_param :number, "Number of the thing", Integer
+        api_method :post, '/thing' do
+          raise "Should never be called"
+        end
+      end
+    
+      expect {
+        post '/thing', {number: '123'}
+      }.to raise_error('Received String, expected Integer for :number')
+    end
+    
+    it 'suppresses parameters that are not defined in the action definition' do
+      @app_class = Class.new(Sinatra::Base) do
+        settings.show_exceptions = false
+        settings.raise_errors = true
+        extend Apiculture
+      
+        api_method :post, '/thing' do
+          raise ":evil_ssh_injection should have wiped from params{}" if params[:evil_ssh_injection]
+          'All is well'
+        end
+      end
+      
+      post '/thing', {evil_ssh_injection: 'I am Homakov!'}
+      expect(last_response).to be_ok
+    end
+    
+    it 'raises when describing a route parameter that is not included in the path' do
+      expect {
+        Class.new(Sinatra::Base) do
+          extend Apiculture
+          route_param :thing_id, "The ID of the thing"
+          api_method(:get, '/thing/:id') { raise "Should never be called" }
+        end
+      }.to raise_error('Parameter :thing_id not present in path "/thing/:id"')
+    end
+    
+    it 'applies a symbol typecast by calling a method on the parameter value' do
+      @app_class = Class.new(Sinatra::Base) do
+        settings.show_exceptions = false
+        settings.raise_errors = true
+        extend Apiculture
+      
+        required_param :number, "Number of the thing", Integer, :cast => :to_i
+        api_method :post, '/thing' do
+          raise "Not cast" unless params[:number] == 123
+          'Total success'
+        end
+      end
+      post '/thing', {number: '123'}
+      expect(last_response.body).to eq('Total success')
+    end
+    
+    it 'applies a Proc typecast by calling the proc (for example - for ISO8601 time)' do
+      @app_class = Class.new(Sinatra::Base) do
+        settings.show_exceptions = false
+        settings.raise_errors = true
+        extend Apiculture
+    
+        required_param :when, "When it happened", Time, cast: ->(v){ Time.parse(v) }
+        api_method :post, '/occurrence' do
+          raise "Not cast" unless params[:when].year == 2015
+          raise "Not cast" unless params[:when].month == 7
+          'Total success'
+        end
+      end
+      post '/occurrence', {when: '2015-07-05T22:16:18Z'}
+      expect(last_response.body).to eq('Total success')
+    end
+  end
+  
+  context 'Sinatra instance method extensions' do
+    it 'adds support for json_response' do
+      @app_class = Class.new(Sinatra::Base) do
+        extend Apiculture
+        settings.show_exceptions = false
+        settings.raise_errors = true
+        api_method :get, '/some-json' do
+          json_response({foo: 'bar'})
+        end
+      end
+      
+      get '/some-json'
+      expect(last_response).to be_ok
+      expect(last_response['Content-Type']).to include('application/json')
+      parsed_body = JSON.load(last_response.body)
+      expect(parsed_body['foo']).to eq('bar')
+    end
+    
+    it 'adds support for json_halt' do
+      @app_class = Class.new(Sinatra::Base) do
+        extend Apiculture
+        settings.show_exceptions = false
+        settings.raise_errors = true
+        api_method :get, '/simple-halt' do
+          json_halt "Nein."
+          raise "This should never be called"
+        end
+        api_method :get, '/halt-with-custom-status' do
+          json_halt 'Nein.', status: 503
+          raise "This should never be called"
+        end
+        api_method :get, '/halt-with-error-payload' do
+          json_halt 'Nein.', teapot: true
+          raise "This should never be called"
+        end
+      end
+      
+      get '/simple-halt'
+      expect(last_response.status).to eq(400)
+      expect(last_response['Content-Type']).to include('application/json')
+      parsed_body = JSON.load(last_response.body)
+      expect(parsed_body).to eq({"error"=>"Nein."})
+      
+      get '/halt-with-error-payload'
+      expect(last_response.status).to eq(400)
+      expect(last_response['Content-Type']).to include('application/json')
+      parsed_body = JSON.load(last_response.body)
+      expect(parsed_body).to eq({"error"=>"Nein.", "teapot"=>true})
+    end
+  end
+end