grape-swagger 0.6.0 → 0.7.0

data/spec/api_models_spec.rb

@@ -0,0 +1,132 @@
+require 'spec_helper'
+
+describe "API Models" do
+
+  before :all do
+    module Entities
+      class Something < Grape::Entity
+        expose :text, :documentation => { :type => "string", :desc => "Content of something." }
+      end
+    end
+
+    module Entities
+      module Some
+        class Thing < Grape::Entity
+          expose :text, :documentation => { :type => "string", :desc => "Content of something." }
+        end
+      end
+    end
+
+    class ModelsApi < Grape::API
+      format :json
+      desc 'This gets something.', {
+        entity: Entities::Something
+      }
+      get '/something' do
+        something = OpenStruct.new text: 'something'
+        present something, with: Entities::Something
+      end
+
+      desc 'This gets thing.', {
+        entity: Entities::Some::Thing
+      }
+      get "/thing" do
+        thing = OpenStruct.new text: 'thing'
+        present thing, with: Entities::Some::Thing
+      end
+      add_swagger_documentation
+    end
+  end
+
+  def app; ModelsApi; end
+
+  it "should document specified models" do
+    get '/swagger_doc'
+    JSON.parse(last_response.body).should == {
+      "apiVersion" => "0.1",
+      "swaggerVersion" => "1.2",
+      "basePath" => "http://example.org",
+      "info" => {},
+      "produces" => ["application/json"],
+      "operations" => [],
+      "apis" => [
+        { "path" => "/something.{format}" },
+        { "path" => "/thing.{format}" },
+        { "path" => "/swagger_doc.{format}" }
+      ]
+    }
+  end
+
+  it "should include type when specified" do
+    get '/swagger_doc/something.json'
+    JSON.parse(last_response.body).should == {
+      "apiVersion" => "0.1",
+      "swaggerVersion" => "1.2",
+      "basePath" => "http://example.org",
+      "resourcePath" => "",
+      "apis" => [{
+        "path" => "/something.{format}",
+        "operations" => [{
+          "produces" => [
+            "application/json"
+          ],
+          "notes" => "",
+          "type" => "Something",
+          "summary" => "This gets something.",
+          "nickname" => "GET-something---format-",
+          "httpMethod" => "GET",
+          "parameters" => []
+        }]
+      }],
+      "models" => {
+        "Something" => {
+          "id" => "Something",
+          "name" => "Something",
+          "properties" => {
+            "text" => {
+              "type" => "string",
+              "description" => "Content of something."
+            }
+          }
+        }
+      }
+    }
+  end
+
+  it "should include nested type when specified" do
+    get '/swagger_doc/thing.json'
+    JSON.parse(last_response.body).should == {
+      "apiVersion" => "0.1",
+      "swaggerVersion" => "1.2",
+      "basePath" => "http://example.org",
+      "resourcePath" => "",
+      "apis" => [{
+        "path" => "/thing.{format}",
+        "operations" => [{
+          "produces" => [
+            "application/json"
+          ],
+          "notes" => "",
+          "type" => "Some::Thing",
+          "summary" => "This gets thing.",
+          "nickname" => "GET-thing---format-",
+          "httpMethod" => "GET",
+          "parameters" => []
+        }]
+      }],
+      "models" => {
+        "Some::Thing" => {
+          "id" => "Some::Thing",
+          "name" => "Some::Thing",
+          "properties" => {
+            "text" => {
+              "type" => "string",
+              "description" => "Content of something."
+            }
+          }
+        }
+      }
+    }
+  end
+
+end

data/spec/default_api_spec.rb

@@ -2,21 +2,91 @@ require 'spec_helper'
 
 describe "Default API" do
 
-  before(:all) do
-    class NotAMountedApi < Grape::API
-      desc 'this gets something'
-      get '/something' do
-        {:bla => 'something'}
+  context 'with no additional options' do
+    before :all do
+      class NotAMountedApi < Grape::API
+        format :json
+        desc 'This gets something.'
+        get '/something' do
+          { bla: 'something' }
+        end
+        add_swagger_documentation
+      end
+    end
+
+    def app; NotAMountedApi; end
+
+    it "should document something" do
+      get '/swagger_doc'
+      JSON.parse(last_response.body).should == {
+        "apiVersion" => "0.1",
+        "swaggerVersion" => "1.2",
+        "basePath" => "http://example.org",
+        "info" => {},
+        "produces" => ["application/json"],
+        "operations" => [],
+        "apis" => [
+          { "path" => "/something.{format}" },
+          { "path" => "/swagger_doc.{format}" }
+        ]
+      }
+    end
+    
+    context "path inside the apis array" do
+      it "should start with a forward slash" do
+        get '/swagger_doc'
+        JSON.parse(last_response.body)['apis'].each do |api|
+          api['path'].should start_with "/"
+        end
       end
-      add_swagger_documentation
     end
   end
 
-  def app; NotAMountedApi; end
+  context 'with API info' do
+    before :all do
+      class ApiInfoTest < Grape::API
+        format :json
+        add_swagger_documentation info: {
+          title: 'My API Title',
+          description: 'A description of my API',
+          license: 'Apache 2',
+          license_url: 'http://test.com',
+          terms_of_service_url: 'http://terms.com',
+          contact: 'support@test.com'
+        }
+      end
+      get '/swagger_doc'
+    end
+
+    def app; ApiInfoTest; end
 
-  it "should document something" do
-    get '/swagger_doc'
-    last_response.body.should == "{:apiVersion=>\"0.1\", :swaggerVersion=>\"1.1\", :basePath=>\"http://example.org\", :operations=>[], :apis=>[{:path=>\"/swagger_doc/something.{format}\"}, {:path=>\"/swagger_doc/swagger_doc.{format}\"}]}"
+    subject do
+      JSON.parse(last_response.body)['info']
+    end
+
+    it 'should document API title' do
+      expect(subject['title']).to eql('My API Title')
+    end
+
+    it 'should document API description' do
+      expect(subject['description']).to eql('A description of my API')
+    end
+
+    it 'should document the license' do
+      expect(subject['license']).to eql('Apache 2')
+    end
+
+    it 'should document the license url' do
+      expect(subject['licenseUrl']).to eql('http://test.com')
+    end
+
+    it 'should document the terms of service url' do
+      expect(subject['termsOfServiceUrl']).to eql('http://terms.com')
+    end
+
+    it 'should document the contact email' do
+      expect(subject['contact']).to eql('support@test.com')
+    end
   end
 
 end

data/spec/form_params_spec.rb

@@ -0,0 +1,83 @@
+require 'spec_helper'
+
+describe "Form Params" do
+
+  before :all do
+    class FormParamApi < Grape::API
+      format :json
+
+      params do
+        requires :name, type: String, desc: "name of item"
+      end
+      post '/items' do
+        {}
+      end
+
+      params do
+        requires :id, type: Integer, desc: "id of item"
+        requires :name, type: String, desc: "name of item"
+      end
+      put '/items/:id' do
+        {}
+      end
+
+      params do
+        requires :id, type: Integer, desc: "id of item"
+        requires :name, type: String, desc: "name of item"
+      end
+      patch '/items/:id' do
+        {}
+      end
+
+      add_swagger_documentation
+    end
+  end
+
+  def app; FormParamApi; end
+
+  it "retrieves the documentation form params" do
+    get '/swagger_doc/items.json'
+
+    JSON.parse(last_response.body).should == {
+      "apiVersion" => "0.1",
+      "swaggerVersion" => "1.2",
+      "resourcePath" => "",
+      "basePath"=>"http://example.org",
+      "apis" => [
+        {
+          "path" => "/items.{format}",
+          "operations" => [
+            {
+              "produces" => ["application/json"],
+              "notes" => "",
+              "summary" => "",
+              "nickname" => "POST-items---format-",
+              "httpMethod" => "POST",
+              "parameters" => [ { "paramType" => "form", "name" => "name", "description" => "name of item", "type" => "String", "dataType" => "String", "required" => true } ]
+            }
+          ]
+        }, {
+          "path" => "/items/{id}.{format}",
+          "operations" => [
+            {
+              "produces" => ["application/json"],
+              "notes" => "",
+              "summary" => "",
+              "nickname" => "PUT-items--id---format-",
+              "httpMethod" => "PUT",
+              "parameters" => [ { "paramType" => "path", "name" => "id", "description" => "id of item", "type" => "Integer", "dataType" => "Integer", "required" => true }, { "paramType" => "form", "name" => "name", "description" => "name of item", "type" => "String", "dataType" => "String", "required" => true } ]
+            },
+            {
+              "produces" => ["application/json"],
+              "notes" => "",
+              "summary" => "",
+              "nickname" => "PATCH-items--id---format-",
+              "httpMethod" => "PATCH",
+              "parameters" => [ { "paramType" => "path", "name" => "id", "description" => "id of item", "type" => "Integer", "dataType" => "Integer", "required" => true }, { "paramType" => "form", "name" => "name", "description" => "name of item", "type" => "String", "dataType" => "String", "required" => true } ]
+            }
+          ]
+        }
+      ]
+    }
+  end
+end

data/spec/grape-swagger_helper_spec.rb

@@ -0,0 +1,107 @@
+require 'spec_helper'
+
+describe "helpers" do
+
+  before :all do
+    class HelperTestAPI < Grape::API
+      add_swagger_documentation
+    end
+  end
+
+  before :each do
+    @api = Object.new
+
+    # after injecting grape-swagger into the Test API we get the helper methods
+    # back from the first endpoint's class (the API mounted by grape-swagger
+    # to serve the swagger_doc
+
+    @api.extend HelperTestAPI.endpoints.first.options[:app].helpers
+  end
+
+  context "parsing parameters" do
+    it "parses params as query strings for a GET" do
+      params = {
+        name: { type: 'String', desc: "A name", required: true, defaultValue: 'default' },
+        level: 'max'
+      }
+      path = "/coolness"
+      method = "GET"
+      @api.parse_params(params, path, method).should == [
+        { paramType: "query", name: :name, description: "A name", type: "String", dataType: "String", required: true, defaultValue: 'default' },
+        { paramType: "query", name: :level, description: "", type: "String", dataType: "String", required: false }
+      ]
+    end
+
+    it "parses params as form for a POST" do
+      params = {
+        name: { type: 'String', :desc => "A name", required: true },
+        level: 'max'
+      }
+      path = "/coolness"
+      method = "POST"
+      @api.parse_params(params, path, method).should == [
+        { paramType: "form", name: :name, description: "A name", type: "String", dataType: "String", required: true },
+        { paramType: "form", name: :level, description: "", type: "String", dataType: "String", required: false }
+      ]
+    end
+
+    context "custom type" do
+      before :all do
+        class CustomType
+        end
+      end
+      it "parses a custom parameters" do
+        params = {
+          option: { type: CustomType, desc: "Custom option" }
+        }
+        path = "/coolness"
+        method = "GET"
+        @api.parse_params(params, path, method).should == [
+          { paramType: "query", name: :option, description: "Custom option", type: "CustomType", dataType: "CustomType", required: false }
+        ]
+      end
+    end
+
+  end
+
+  context "parsing the path" do
+    it "parses the path" do
+      path = ":abc/def(.:format)"
+      @api.parse_path(path, nil).should == "{abc}/def.{format}"
+    end
+
+    it "parses a path that has vars with underscores in the name" do
+      path = "abc/:def_g(.:format)"
+      @api.parse_path(path, nil).should == "abc/{def_g}.{format}"
+    end
+
+    it "parses a path that has vars with numbers in the name" do
+      path = "abc/:sha1(.:format)"
+      @api.parse_path(path, nil).should == "abc/{sha1}.{format}"
+    end
+
+    it "parses a path that has multiple variables" do
+      path1 = "abc/:def/:geh(.:format)"
+      path2 = "abc/:def:geh(.:format)"
+      @api.parse_path(path1, nil).should == "abc/{def}/{geh}.{format}"
+      @api.parse_path(path2, nil).should == "abc/{def}{geh}.{format}"
+    end
+
+    it "parses the path with a specified version" do
+      path = ":abc/{version}/def(.:format)"
+      @api.parse_path(path, 'v1').should == "{abc}/v1/def.{format}"
+    end
+  end
+
+  context "parsing header parameters" do
+    it "parses params for the header" do
+      params = {
+        "XAuthToken" => { description: "A required header.", required: true, defaultValue: 'default' }
+      }
+      @api.parse_header_params(params).should == [
+        { paramType: "header", name: "XAuthToken", description: "A required header.", type: "String", dataType: "String", required: true, defaultValue: 'default' }
+      ]
+    end
+  end
+
+end

data/spec/grape-swagger_spec.rb

@@ -10,6 +10,4 @@ describe Grape::API do
     Grape::API.should respond_to :add_swagger_documentation
   end
 
-
-
 end

data/spec/hide_api_spec.rb

@@ -0,0 +1,106 @@
+require 'spec_helper'
+
+describe "a hide mounted api" do
+  before :all do
+    class HideMountedApi < Grape::API
+      desc 'Show this endpoint'
+      get '/simple' do
+        { :foo => 'bar' }
+      end
+
+      desc 'Hide this endpoint', {
+        :hidden => true
+      }
+      get '/hide' do
+        { :foo => 'bar' }
+      end
+    end
+
+    class HideApi < Grape::API
+      mount HideMountedApi
+      add_swagger_documentation
+    end
+  end
+
+  def app; HideApi end
+
+  it "retrieves swagger-documentation that doesn't include hidden endpoints" do
+    get '/swagger_doc.json'
+    JSON.parse(last_response.body).should == {
+      "apiVersion" => "0.1",
+      "swaggerVersion" => "1.2",
+      "basePath" => "http://example.org",
+      "info" => {},
+      "produces" => ["application/xml", "application/json", "text/plain"],
+      "operations" => [],
+      "apis" => [
+        { "path" => "/simple.{format}" },
+        { "path" => "/swagger_doc.{format}" }
+      ]
+    }
+  end
+end
+
+
+describe "a hide mounted api with same namespace" do
+  before :all do
+    class HideNamespaceMountedApi < Grape::API
+      desc 'Show this endpoint'
+      get '/simple/show' do
+        { :foo => 'bar' }
+      end
+
+      desc 'Hide this endpoint', {
+        :hidden => true
+      }
+      get '/simple/hide' do
+        { :foo => 'bar' }
+      end
+    end
+
+    class HideNamespaceApi < Grape::API
+      mount HideNamespaceMountedApi
+      add_swagger_documentation
+    end
+  end
+
+  def app; HideNamespaceApi end
+
+  it "retrieves swagger-documentation on /swagger_doc" do
+    get '/swagger_doc.json'
+    JSON.parse(last_response.body).should == {
+      "apiVersion" => "0.1",
+      "swaggerVersion" => "1.2",
+      "basePath" => "http://example.org",
+      "info" => {},
+      "produces" => ["application/xml", "application/json", "text/plain"],
+      "operations" => [],
+      "apis" => [
+        { "path" => "/simple.{format}" },
+        { "path" => "/swagger_doc.{format}" }
+      ]
+    }
+  end
+
+  it "retrieves the documentation for mounted-api that doesn't include hidden endpoints" do
+    get '/swagger_doc/simple.json'
+    JSON.parse(last_response.body).should == {
+      "apiVersion" => "0.1",
+      "swaggerVersion" => "1.2",
+      "basePath" => "http://example.org",
+      "resourcePath" => "",
+      "apis" => [{
+        "path" => "/simple/show.{format}",
+        "operations" => [{
+          "produces" => ["application/xml", "application/json", "text/plain"],
+          "notes" => nil,
+          "notes" => "",
+          "summary" => "Show this endpoint",
+          "nickname" => "GET-simple-show---format-",
+          "httpMethod" => "GET",
+          "parameters" => []
+        }]
+      }]
+    }
+  end
+end