grape-swagger 0.7.2 → 0.8.0

data/spec/response_model_spec.rb

@@ -0,0 +1,80 @@
+require 'spec_helper'
+
+describe 'responseModel' do
+  before :all do
+    module MyAPI
+      module Entities
+        class BaseEntity < Grape::Entity
+          def self.entity_name
+            name.sub(/^MyAPI::Entities::/, '')
+          end
+        end
+
+        class Something < BaseEntity
+          expose :text, documentation: { type: 'string', desc: 'Content of something.' }
+        end
+
+        class Error < BaseEntity
+          expose :code, documentation: { type: 'string', desc: 'Error code' }
+          expose :message, documentation: { type: 'string', desc: 'Error message' }
+        end
+      end
+
+      class ResponseModelApi < Grape::API
+        format :json
+        desc 'This returns something or an error',
+             entity: Entities::Something,
+             http_codes: [
+               [200, 'OK', Entities::Something],
+               [403, 'Refused to return something', Entities::Error]
+             ]
+
+        get '/something/:id' do
+          if params[:id] == 1
+            something = OpenStruct.new text: 'something'
+            present something, with: Entities::Something
+          else
+            error = OpenStruct.new code: 'some_error', message: 'Some error'
+            present error, with: Entities::Error
+          end
+        end
+
+        add_swagger_documentation
+      end
+    end
+  end
+
+  def app
+    MyAPI::ResponseModelApi
+  end
+
+  subject do
+    get '/swagger_doc/something'
+    JSON.parse(last_response.body)
+  end
+
+  it 'should document specified models' do
+    expect(subject['apis'][0]['operations'][0]['responseMessages']).to eq(
+      [
+        {
+          'code' => 200,
+          'message' => 'OK',
+          'responseModel' => 'Something'
+        },
+        {
+          'code' => 403,
+          'message' => 'Refused to return something',
+          'responseModel' => 'Error'
+        }
+      ]
+    )
+    expect(subject['models'].keys).to include 'Error'
+    expect(subject['models']['Error']).to eq(
+      'id' => 'Error',
+      'properties' => {
+        'code' => { 'type' => 'string', 'description' => 'Error code' },
+        'message' => { 'type' => 'string', 'description' => 'Error message' }
+      }
+    )
+  end
+end

data/spec/simple_mounted_api_spec.rb

@@ -1,58 +1,56 @@
 require 'spec_helper'
 
-describe "a simple mounted api" do
+describe 'a simple mounted api' do
   before :all do
     class CustomType; end
 
     class SimpleMountedApi < Grape::API
-      desc "Document root"
+      desc 'Document root'
       get do
       end
 
-      desc 'This gets something.', {
-        :notes => '_test_'
-      }
+      desc 'This gets something.',
+           notes: '_test_'
 
       get '/simple' do
         { bla: 'something' }
       end
 
-      desc 'This gets something for URL using - separator.', {
-        :notes => '_test_'
-      }
+      desc 'This gets something for URL using - separator.',
+           notes: '_test_'
 
       get '/simple-test' do
         { bla: 'something' }
       end
 
-      desc 'this gets something else', {
-        :headers => {
-          "XAuthToken" => { description: "A required header.", required: true },
-          "XOtherHeader" => { description: "An optional header.", required: false }
-        },
-        :http_codes => {
-          403 => "invalid pony",
-          405 => "no ponies left!"
-        }
-      }
+      desc 'this gets something else',
+           headers: {
+             'XAuthToken' => { description: 'A required header.', required: true },
+             'XOtherHeader' => { description: 'An optional header.', required: false }
+           },
+           http_codes: {
+             403 => 'invalid pony',
+             405 => 'no ponies left!'
+           }
+
       get '/simple_with_headers' do
-        {:bla => 'something_else'}
+        { bla: 'something_else' }
       end
 
-      desc 'this takes an array of parameters', {
-        :params => {
-          "items[]" => { description: "array of items" }
-        }
-      }
+      desc 'this takes an array of parameters',
+           params: {
+             'items[]' => { description: 'array of items' }
+           }
+
       post '/items' do
         {}
       end
 
-      desc 'this uses a custom parameter', {
-        :params => {
-          "custom" => { type: CustomType, description: "array of items" }
-        }
-      }
+      desc 'this uses a custom parameter',
+           params: {
+             'custom' => { type: CustomType, description: 'array of items' }
+           }
+
       get '/custom' do
         {}
       end
@@ -64,126 +62,123 @@ describe "a simple mounted api" do
     end
   end
 
-  def app; SimpleApi end
+  def app
+    SimpleApi
+  end
 
-  it "retrieves swagger-documentation on /swagger_doc" do
+  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" => "/swagger_doc/simple.{format}" },
-        { "path" => "/swagger_doc/simple-test.{format}" },
-        { "path" => "/swagger_doc/simple_with_headers.{format}" },
-        { "path" => "/swagger_doc/items.{format}" },
-        { "path" => "/swagger_doc/custom.{format}" },
-        { "path" => "/swagger_doc/swagger_doc.{format}" }
+    expect(JSON.parse(last_response.body)).to eq(
+      'apiVersion' => '0.1',
+      'swaggerVersion' => '1.2',
+      'info' => {},
+      'produces' => ['application/xml', 'application/json', 'application/vnd.api+json', 'text/plain'],
+      'apis' => [
+        { 'path' => '/simple.{format}', 'description' => 'Operations about simples' },
+        { 'path' => '/simple-test.{format}', 'description' => 'Operations about simple-tests' },
+        { 'path' => '/simple_with_headers.{format}', 'description' => 'Operations about simple_with_headers' },
+        { 'path' => '/items.{format}', 'description' => 'Operations about items' },
+        { 'path' => '/custom.{format}', 'description' => 'Operations about customs' },
+        { 'path' => '/swagger_doc.{format}', 'description' => 'Operations about swagger_docs' }
       ]
-    }
+    )
   end
 
-  it "retrieves the documentation for mounted-api" do
+  it 'retrieves the documentation for mounted-api' 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.{format}",
-        "operations" => [{
-          "produces" => ["application/xml", "application/json", "text/plain"],
-          "notes" => "_test_",
-          "summary" => "This gets something.",
-          "nickname" => "GET-simple---format-",
-          "httpMethod" => "GET",
-          "parameters" => []
+    expect(JSON.parse(last_response.body)).to eq(
+      'apiVersion' => '0.1',
+      'swaggerVersion' => '1.2',
+      'basePath' => 'http://example.org',
+      'resourcePath' => '/simple',
+      'produces' => ['application/xml', 'application/json', 'application/vnd.api+json', 'text/plain'],
+      'apis' => [{
+        'path' => '/simple.{format}',
+        'operations' => [{
+          'notes' => '_test_',
+          'summary' => 'This gets something.',
+          'nickname' => 'GET-simple---format-',
+          'method' => 'GET',
+          'parameters' => [],
+          'type' => 'void'
         }]
       }]
-    }
+    )
   end
 
-  context "retrieves the documentation for mounted-api that" do
+  context 'retrieves the documentation for mounted-api that' do
     it "contains '-' in URL" do
       get '/swagger_doc/simple-test.json'
-      JSON.parse(last_response.body).should == {
-        "apiVersion" => "0.1",
-        "swaggerVersion" => "1.2",
-        "basePath" => "http://example.org",
-        "resourcePath" => "",
-        "apis" => [{
-          "path" => "/simple-test.{format}",
-          "operations" => [{
-            "produces" => ["application/xml", "application/json", "text/plain"],
-            "notes" => "_test_",
-            "summary" => "This gets something for URL using - separator.",
-            "nickname" => "GET-simple-test---format-",
-            "httpMethod" => "GET",
-            "parameters" => []
+      expect(JSON.parse(last_response.body)).to eq(
+        'apiVersion' => '0.1',
+        'swaggerVersion' => '1.2',
+        'basePath' => 'http://example.org',
+        'resourcePath' => '/simple-test',
+        'produces' => ['application/xml', 'application/json', 'application/vnd.api+json', 'text/plain'],
+        'apis' => [{
+          'path' => '/simple-test.{format}',
+          'operations' => [{
+            'notes' => '_test_',
+            'summary' => 'This gets something for URL using - separator.',
+            'nickname' => 'GET-simple-test---format-',
+            'method' => 'GET',
+            'parameters' => [],
+            'type' => 'void'
           }]
         }]
-      }
+      )
     end
 
-    it "includes headers" do
+    it 'includes headers' do
       get '/swagger_doc/simple_with_headers.json'
-      JSON.parse(last_response.body)["apis"].should == [{
-        "path" => "/simple_with_headers.{format}",
-        "operations" => [{
-          "produces" => ["application/xml", "application/json", "text/plain"],
-          "notes" => nil,
-          "notes" => "",
-          "summary" => "this gets something else",
-          "nickname" => "GET-simple_with_headers---format-",
-          "httpMethod" => "GET",
-          "parameters" => [
-            { "paramType" => "header", "name" => "XAuthToken", "description" => "A required header.", "type" => "String", "dataType" => "String", "required" => true },
-            { "paramType" => "header", "name" => "XOtherHeader", "description" => "An optional header.", "type" => "String", "dataType" => "String", "required" => false }
+      expect(JSON.parse(last_response.body)['apis']).to eq [{
+        'path' => '/simple_with_headers.{format}',
+        'operations' => [{
+          'notes' => '',
+          'summary' => 'this gets something else',
+          'nickname' => 'GET-simple_with_headers---format-',
+          'method' => 'GET',
+          'parameters' => [
+            { 'paramType' => 'header', 'name' => 'XAuthToken', 'description' => 'A required header.', 'type' => 'String', 'required' => true },
+            { 'paramType' => 'header', 'name' => 'XOtherHeader', 'description' => 'An optional header.', 'type' => 'String', 'required' => false }
           ],
-          "responseMessages" => [
-            { "code" => 403, "message" => "invalid pony" },
-            { "code" => 405, "message" => "no ponies left!" }
+          'type' => 'void',
+          'responseMessages' => [
+            { 'code' => 403, 'message' => 'invalid pony' },
+            { 'code' => 405, 'message' => 'no ponies left!' }
           ]
         }]
       }]
     end
 
-    it "supports multiple parameters" do
+    it 'supports multiple parameters' do
       get '/swagger_doc/items.json'
-      JSON.parse(last_response.body)["apis"].should == [{
-        "path" => "/items.{format}",
-        "operations" => [{
-          "produces" => ["application/xml", "application/json", "text/plain"],
-          "notes" => nil,
-          "notes" => "",
-          "summary" => "this takes an array of parameters",
-          "nickname" => "POST-items---format-",
-          "httpMethod" => "POST",
-          "parameters" => [ { "paramType" => "form", "name" => "items[]", "description" => "array of items", "type" => "String", "dataType" => "String", "required" => false } ]
+      expect(JSON.parse(last_response.body)['apis']).to eq [{
+        'path' => '/items.{format}',
+        'operations' => [{
+          'notes' => '',
+          'summary' => 'this takes an array of parameters',
+          'nickname' => 'POST-items---format-',
+          'method' => 'POST',
+          'parameters' => [{ 'paramType' => 'form', 'name' => 'items[]', 'description' => 'array of items', 'type' => 'string', 'required' => false, 'allowMultiple' => false }],
+          'type' => 'void'
         }]
       }]
     end
 
-    it "supports custom types" do
+    it 'supports custom types' do
       get '/swagger_doc/custom.json'
-      JSON.parse(last_response.body)["apis"].should == [{
-        "path" => "/custom.{format}",
-        "operations" => [{
-          "produces" => ["application/xml", "application/json", "text/plain"],
-          "notes" => nil,
-          "notes" => "",
-          "summary" => "this uses a custom parameter",
-          "nickname" => "GET-custom---format-",
-          "httpMethod" => "GET",
-          "parameters" => [ { "paramType" => "query", "name" => "custom", "description" => "array of items", "type" => "CustomType", "dataType" => "CustomType", "required" => false } ]
+      expect(JSON.parse(last_response.body)['apis']).to eq [{
+        'path' => '/custom.{format}',
+        'operations' => [{
+          'notes' => '',
+          'summary' => 'this uses a custom parameter',
+          'nickname' => 'GET-custom---format-',
+          'method' => 'GET',
+          'parameters' => [{ 'paramType' => 'query', 'name' => 'custom', 'description' => 'array of items', 'type' => 'CustomType', 'required' => false, 'allowMultiple' => false }],
+          'type' => 'void'
         }]
       }]
     end
-
   end
-
 end

data/spec/spec_helper.rb

@@ -9,7 +9,6 @@ require 'grape-entity'
 require 'rubygems'
 require 'bundler'
 
-require 'pry'
 require 'json'
 
 Bundler.setup :default, :test

data/spec/version_spec.rb

@@ -0,0 +1,8 @@
+require 'spec_helper'
+
+describe GrapeSwagger do
+  it '#version' do
+    expect(GrapeSwagger::VERSION).to_not be_nil
+    expect(GrapeSwagger::VERSION.split('.').count).to eq 3
+  end
+end

data/test/api.rb

@@ -0,0 +1,62 @@
+require 'grape'
+require '../lib/grape-swagger'
+
+@@splines = {}
+
+class Api < Grape::API
+  format :json
+
+  desc 'API Root'
+  get do
+    { splines_url: '/splines' }
+  end
+
+  namespace :splines do
+    desc 'Return a spline.'
+    params do
+      requires :id, type: Integer, desc: 'Spline id.'
+    end
+    get ':id' do
+      @@splines[params[:id]] || error!('Not Found', 404)
+    end
+
+    desc 'Update a spline.'
+    params do
+      requires :id, type: Integer, desc: 'Spline id.'
+      optional :reticulated, type: Boolean, default: true, desc: 'True if the spline is reticulated.'
+    end
+    put ':id' do
+      spline = (@@splines[params[:id]] || error!('Not Found', 404))
+      spline[:reticulated] = params[:reticulated]
+      spline
+    end
+
+    desc 'Create a spline.'
+    params do
+      optional :reticulated, type: Boolean, default: true, desc: 'True if the spline is reticulated.'
+    end
+    post do
+      spline = { id: @@splines.size + 1, reticulated: params[:reticulated] }
+      @@splines[@@splines.size + 1] = spline
+      spline
+    end
+
+    desc 'Return all splines.'
+    get do
+      @@splines.values
+    end
+
+    # TEST api for testing uploading
+    # curl --form file=@splines.png http://localhost:9292/splines/upload
+    desc 'Update image'
+    post 'upload' do
+      filename = params[:file][:filename]
+      content_type 'application/octet-stream'
+      env['api.format'] = :binary # there's no formatter for :binary, data will be returned "as is"
+      header 'Content-Disposition', "attachment; filename*=UTF-8''#{URI.escape(filename)}"
+      params[:file][:tempfile].read
+    end
+  end
+
+  add_swagger_documentation
+end