swagger-doc-rails 1.0.0

data/lib/swagger/docs/impotent_methods.rb

@@ -0,0 +1,24 @@
+module Swagger
+  module Docs
+    module ImpotentMethods
+
+      def self.included(base)
+        base.extend ClassMethods
+      end
+
+      module ClassMethods
+        private
+
+        def swagger_api(action, params = {}, &block)
+        end
+
+        def swagger_model(model_name, &block)
+        end
+
+        def swagger_controller(controller, description, params={})
+        end
+      end
+
+    end
+  end
+end

data/lib/swagger/docs/methods.rb

@@ -0,0 +1,52 @@
+require "active_support/core_ext/hash/deep_merge"
+module Swagger
+  module Docs
+    module Methods
+      def self.included(base)
+        base.extend ClassMethods
+      end
+
+      module ClassMethods
+        def swagger_controller(controller, description, params = {})
+          swagger_config[:controller] = controller
+          swagger_config[:description] = description
+          swagger_config[:resource_path] = params[:resource_path]
+        end
+
+        def swagger_actions
+          swagger_dsl = {}
+          Array(@swagger_dsl).each do |action, params, controller, block|
+            dsl = SwaggerDSL.call(action, controller, &block)
+            swagger_dsl[action] ||= {}
+            swagger_dsl[action].deep_merge!(dsl) { |key, old, new| Array(old) + Array(new) }
+            swagger_dsl[action].deep_merge!(params) # merge in user api parameters
+          end
+          swagger_dsl
+        end
+
+        def swagger_models
+          swagger_model_dsls ||= {}
+          Array(@swagger_model_dsls).each do |model_name, controller, block|
+            model_dsl = SwaggerModelDSL.call(model_name, controller, &block)
+            swagger_model_dsls[model_name] = model_dsl
+          end
+          swagger_model_dsls
+        end
+
+        def swagger_config
+          @swagger_config ||= {}
+        end
+
+        def swagger_api(action, params = {}, &block)
+          @swagger_dsl ||= []
+          @swagger_dsl << [action, params, self, block]
+        end
+
+        def swagger_model(model_name, &block)
+          @swagger_model_dsls ||= []
+          @swagger_model_dsls << [model_name, self, block]
+        end
+      end
+    end
+  end
+end

data/lib/swagger/docs/task.rb

@@ -0,0 +1,9 @@
+module Swagger
+  module Docs
+    class Task < Rails::Railtie
+      rake_tasks do
+        Dir[File.join(File.dirname(__FILE__),'../../tasks/*.rake')].each { |f| load f }
+      end
+    end
+  end
+end

data/lib/swagger/docs/version.rb

@@ -0,0 +1,5 @@
+module Swagger
+  module Docs
+    VERSION = "1.0.0"
+  end
+end

data/lib/tasks/swagger.rake

@@ -0,0 +1,10 @@
+namespace :swagger do
+
+  desc "Generate Swagger documentation files"
+  task :docs => [:environment] do |t,args|
+    results = Swagger::Docs::Generator.write_docs(Swagger::Docs::Config.registered_apis)
+    results.each do |k,v|
+      puts "#{k}: #{v[:processed].count} processed / #{v[:skipped].count} skipped"
+    end
+  end
+end

data/spec/fixtures/controllers/application_controller.rb

@@ -0,0 +1,4 @@
+class ApplicationController
+  cattr_accessor :context
+  self.context = "original"
+end

data/spec/fixtures/controllers/custom_resource_path_controller.rb

@@ -0,0 +1,18 @@
+module Api
+  module V1
+    class SuperclassController < ApplicationController
+    end
+    class CustomResourcePathController < SuperclassController
+      swagger_controller :custom_resource_path, "User Management", resource_path: "resource/testing"
+
+      swagger_api :index do
+        summary "Fetches all User items"
+        param :query, :page, :integer, :optional, "Page number"
+        param :path, :nested_id, :integer, :optional, "Team Id"
+        response :unauthorized
+        response :not_acceptable, "The request you made is not acceptable"
+        response :requested_range_not_satisfiable
+      end
+    end
+  end
+end

data/spec/fixtures/controllers/ignored_controller.rb

@@ -0,0 +1,6 @@
+module Api
+  module V1
+    class IgnoredController
+    end
+  end
+end

data/spec/fixtures/controllers/multiple_routes_controller.rb

@@ -0,0 +1,13 @@
+module Api
+  module V1
+    class MultipleRoutesController < ApplicationController
+        swagger_controller :multiple_routes, "Multiple Routes"
+
+        swagger_api :index do
+        summary "Creates a new User"
+        param :form, :first_name, :string, :required, "First name"
+        response :unauthorized
+      end
+    end
+  end
+end

data/spec/fixtures/controllers/nested_controller.rb

@@ -0,0 +1,18 @@
+module Api
+  module V1
+    class SuperclassController < ApplicationController
+    end
+    class NestedController < SuperclassController
+      swagger_controller :nested, "User Management"
+
+      swagger_api :index do
+        summary "Fetches all User items"
+        param :query, :page, :integer, :optional, "Page number"
+        param :path, :nested_id, :integer, :optional, "Team Id"
+        response :unauthorized
+        response :not_acceptable, "The request you made is not acceptable"
+        response :requested_range_not_satisfiable
+      end
+    end
+  end
+end

data/spec/fixtures/controllers/sample_controller.rb

@@ -0,0 +1,81 @@
+module Api
+  module V1
+    class SuperclassController < ApplicationController
+    end
+    class SampleController < SuperclassController
+      swagger_controller :users, "User Management"
+
+      swagger_api :index do
+        summary "Fetches all User items"
+        param :query, :page, :integer, :optional, "Page number"
+        param :path, :nested_id, :integer, :optional, "Team Id"
+        response :ok, "Some text", :Tag
+        response :unauthorized
+        response :not_acceptable, "The request you made is not acceptable"
+        response :requested_range_not_satisfiable
+      end
+
+      swagger_api :show do
+        summary "Fetches a single User item"
+        param :path, :id, :integer, :optional, "User Id"
+        response :unauthorized
+        response :not_acceptable
+        response :not_found
+      end
+
+      swagger_api :create do
+        summary "Creates a new User"
+        consumes [ "application/json", "text/xml" ]
+        param :form, :first_name, :string, :required, "First name"
+        param :form, :last_name, :string, :required, "Last name"
+        param :form, :email, :string, :required, "Email address"
+        param_list :form, :role, :string, :required, "Role", [ "admin", "superadmin", "user" ]
+        param :body, :body, :json, :required, 'JSON formatted body'
+        items '{$ref" => "setup"}'
+        response :unauthorized
+        response :not_acceptable
+      end
+
+      swagger_api :update do
+        summary "Updates an existing User"
+        notes "Only the given fields are updated."
+        param :path, :id, :integer, :required, "User Id"
+        param :form, :first_name, :string, :optional, "First name"
+        param :form, :last_name, :string, :optional, "Last name"
+        param :form, :email, :string, :optional, "Email address"
+        param :form, :tag, :Tag, :required, "Tag object"
+        response :unauthorized
+        response :not_found
+        response :not_acceptable
+      end
+
+      swagger_api :destroy do
+        summary "Deletes an existing User item"
+        param :path, :id, :integer, :optional, "User Id"
+        response :unauthorized
+        response :not_found
+      end
+
+      # a method that intentionally has no parameters
+      swagger_api :new do
+        summary "Builds a new User item"
+      end
+
+      swagger_api :context_dependent do
+        summary "An action dependent on the context of the controller " +
+          "class. Right now it is: " + ApplicationController.context
+        response :ok
+        response :unauthorized
+      end
+
+      # Support for Swagger complex types:
+      # https://github.com/wordnik/swagger-core/wiki/Datatypes#wiki-complex-types
+      swagger_model :Tag do
+        description "A Tag object."
+        property :id, :integer, :required, "User Id"
+        property :name, :string, :optional, "Name", foo: "test"
+        property_list :type, :string, :optional, "Type", ["info", "warning", "error"]
+      end
+    end
+  end
+end

data/spec/lib/swagger/docs/api_declaration_file_metadata_spec.rb

@@ -0,0 +1,48 @@
+require 'spec_helper'
+
+describe Swagger::Docs::ApiDeclarationFileMetadata do
+
+  describe "#initialize" do
+    it "sets the api_version property" do
+      metadata = described_class.new("1.0", "path", "basePath", "controllerBasePath")
+      expect(metadata.api_version).to eq("1.0")
+    end
+    it "sets the path property" do
+      metadata = described_class.new("1.0", "path", "basePath", "controllerBasePath")
+      expect(metadata.path).to eq("path")
+    end
+    it "sets the base_path property" do
+      metadata = described_class.new("1.0", "path", "basePath", "controllerBasePath")
+      expect(metadata.base_path).to eq("basePath")
+    end
+    it "sets the controller_base_path property" do
+      metadata = described_class.new("1.0", "path", "basePath", "controllerBasePath")
+      expect(metadata.controller_base_path).to eq("controllerBasePath")
+    end
+    it "defaults the swagger_version property to DEFAULT_SWAGGER_VERSION" do
+      metadata = described_class.new("1.0", "path", "basePath", "controllerBasePath")
+      expect(metadata.swagger_version).to eq(described_class::DEFAULT_SWAGGER_VERSION)
+    end
+    it "allows the swagger_version property to be_overriden" do
+      metadata = described_class.new("1.0", "path", "basePath", "controllerBasePath", swagger_version: "2.0")
+      expect(metadata.swagger_version).to eq("2.0")
+    end
+    it "defaults the camelize_model_properties property to true" do
+      metadata = described_class.new("1.0", "path", "basePath", "controllerBasePath")
+      expect(metadata.camelize_model_properties).to eq(true)
+    end
+    it "allows the camelize_model_properties property to be overidden" do
+      metadata = described_class.new("1.0", "path", "basePath", "controllerBasePath", camelize_model_properties: false)
+      expect(metadata.camelize_model_properties).to eq(false)
+    end
+    it "defaults the authorizations property to empty hash" do
+     metadata = described_class.new("1.0", "path", "basePath", "controllerBasePath")
+     expect(metadata.authorizations).to eq({})
+    end
+    it "allows the authorizations property to be overidden" do
+     authorizations = {foo: 'bar'}
+     metadata = described_class.new("1.0", "path", "basePath", "controllerBasePath", authorizations: authorizations)
+     expect(metadata.authorizations).to eq(authorizations)
+    end
+  end
+end

data/spec/lib/swagger/docs/api_declaration_file_spec.rb

@@ -0,0 +1,203 @@
+require "spec_helper"
+
+describe Swagger::Docs::ApiDeclarationFile do
+  let(:apis) do
+    [
+      {
+        :path=>"sample/{id}",
+        :operations=>[
+          {
+            :summary=>"Updates an existing User",
+            :parameters=>[
+              {:param_type=>:path, :name=>:id, :type=>:integer, :description=>"User Id", :required=>true},
+              {:param_type=>:form, :name=>:first_name, :type=>:string, :description=>"First name", :required=>false},
+              {:param_type=>:form, :name=>:last_name, :type=>:string, :description=>"Last name", :required=>false},
+              {:param_type=>:form, :name=>:email, :type=>:string, :description=>"Email address", :required=>false},
+              {:param_type=>:form, :name=>:tag, :type=>:Tag, :description=>"Tag object", :required=>true}
+            ],
+            :response_messages=>[
+              {:code=>401, :message=>"Unauthorized"},
+              {:code=>404, :message=>"Not Found"},
+              {:code=>406, :message=>"Not Acceptable"}
+            ],
+            :notes=>"Only the given fields are updated.",
+            :method=>:put,
+            :nickname=>"Api::V1::Sample#update",
+            :consumes=>["application/json", "text/xml"]
+          }
+        ]
+      }
+    ]
+  end
+  let(:models) do
+    {
+      :Tag=>
+      {
+        :id=>:Tag,
+        :required=>[:id],
+        :properties=>
+        {
+          :id=>{:type=>:integer, :description=>"User Id"},
+          :first_name=>{:type=>:string, :description=>"First Name"},
+          :last_name=>{:type=>:string, :description=>"Last Name"}
+        },
+        :description=>"A Tag object."
+      }
+    }
+  end
+  let(:metadata) do
+    Swagger::Docs::ApiDeclarationFileMetadata.new("1.0", "api/v1/sample", "http://api.no.where/", "")
+  end
+
+  describe "#generate_resource" do
+    it "generates the appropriate response" do
+      declaration = described_class.new(metadata, apis, models)
+
+      expected_response = {
+        "apiVersion"=> declaration.api_version,
+        "swaggerVersion"=> declaration.swagger_version,
+        "basePath"=> declaration.base_path,
+        "apis"=> declaration.apis,
+        "resourcePath"=> declaration.resource_path,
+        :models=> declaration.models,
+        "resourceFilePath" => declaration.resource_file_path,
+        "authorizations" => {}
+      }
+      expect(declaration.generate_resource).to eq(expected_response)
+    end
+  end
+  describe "#base_path" do
+    it "returns metadata.base_path" do
+      metadata = double("metadata", base_path: "/hello")
+      declaration = described_class.new(metadata, apis, models)
+      expect(declaration.base_path).to eq(metadata.base_path)
+    end
+  end
+  describe "#path" do
+    it "returns metadata.path" do
+      metadata = double("metadata", path: "/hello")
+      declaration = described_class.new(metadata, apis, models)
+      expect(declaration.path).to eq(metadata.path)
+    end
+  end
+  describe "#controller_base_path" do
+    it "returns metadata.controller_base_path" do
+      metadata = double("metadata", controller_base_path: "/hello")
+      declaration = described_class.new(metadata, apis, models)
+      expect(declaration.controller_base_path).to eq(metadata.controller_base_path)
+    end
+  end
+  describe "#resource_path" do
+    it "returns the debased controller path" do
+      metadata = double("metadata", overridden_resource_path: nil, controller_base_path: "/hello", path: "/hello/test-endpoint")
+      declaration = described_class.new(metadata, apis, models)
+      expect(declaration.resource_path).to eq("test_endpoint")
+   end
+   context "with an overridden_resource_path" do
+     it "returns the overriden resource path directly" do
+      metadata = double("metadata", overridden_resource_path: "testing-path", controller_base_path: "/hello", path: "/hello/test-endpoint")
+      declaration = described_class.new(metadata, apis, models)
+      expect(declaration.resource_path).to eq("testing-path")
+      end
+    end
+  end
+  describe "#swagger_version" do
+    it "returns metadata.swagger_version" do
+      metadata = double("metadata", swagger_version: "1.2")
+      declaration = described_class.new(metadata, apis, models)
+      expect(declaration.swagger_version).to eq(metadata.swagger_version)
+    end
+  end
+  describe "#api_version" do
+    it "returns metadata.api_version" do
+      metadata = double("metadata", api_version: "1.0")
+      declaration = described_class.new(metadata, apis, models)
+      expect(declaration.api_version).to eq(metadata.api_version)
+    end
+  end
+  describe "#camelize_model_properties" do
+    it "returns metadata.camelize_model_properties" do
+      metadata = double("metadata", camelize_model_properties: false)
+      declaration = described_class.new(metadata, apis, models)
+      expect(declaration.camelize_model_properties).to eq(metadata.camelize_model_properties)
+    end
+  end
+  describe "#models" do
+    context "with camelize_model_properties set to true" do
+      it "returns a models hash that's ready for output" do
+        declaration = described_class.new(metadata, apis, models)
+        allow(declaration).to receive(:camelize_model_properties).and_return(true)
+        expected_models_hash = {
+          "Tag" =>
+          {
+            "id" => :Tag,
+            "required" =>[:id],
+            "properties" =>
+            {
+              "id" =>{"type"=>:integer, "description"=>"User Id"},
+              "firstName"=>{"type"=>:string, "description"=>"First Name"},
+              "lastName"=>{"type"=>:string, "description"=>"Last Name"},
+            },
+            "description"=>"A Tag object."
+          }
+        }
+
+        expect(declaration.models).to eq(expected_models_hash)
+      end
+    end
+    context "with camelize_model_properties set to false" do
+      it "returns a models hash that's ready for output" do
+        declaration = described_class.new(metadata, apis, models)
+        allow(declaration).to receive(:camelize_model_properties).and_return(false)
+        expected_models_hash = {
+          "Tag" =>
+          {
+            "id" => :Tag,
+            "required" =>[:id],
+            "properties" =>
+            {
+              "id" =>{"type"=>:integer, "description"=>"User Id"},
+              "first_name"=>{"type"=>:string, "description"=>"First Name"},
+              "last_name"=>{"type"=>:string, "description"=>"Last Name"},
+            },
+            "description"=>"A Tag object."
+          }
+        }
+
+        expect(declaration.models).to eq(expected_models_hash)
+      end
+    end
+  end
+  describe "#apis" do
+    it "returns a api hash that's ready for output" do
+      declaration = described_class.new(metadata, apis, models)
+      expected_apis_array = [
+        {
+          "path"=>"sample/{id}",
+          "operations"=>[
+            {
+              "summary"=>"Updates an existing User",
+              "parameters"=>[
+                {"paramType"=>:path, "name"=>:id, "type"=>:integer, "description"=>"User Id", "required"=>true},
+                {"paramType"=>:form, "name"=>:first_name, "type"=>:string, "description"=>"First name", "required"=>false},
+                {"paramType"=>:form, "name"=>:last_name, "type"=>:string, "description"=>"Last name", "required"=>false},
+                {"paramType"=>:form, "name"=>:email, "type"=>:string, "description"=>"Email address", "required"=>false},
+                {"paramType"=>:form, "name"=>:tag, "type"=>:Tag, "description"=>"Tag object", "required"=>true}
+              ],
+              "responseMessages"=>[
+                {"code"=>401, "message"=>"Unauthorized"},
+                {"code"=>404, "message"=>"Not Found"},
+                {"code"=>406, "message"=>"Not Acceptable"}
+              ],
+              "notes"=>"Only the given fields are updated.",
+              "method"=>:put,
+              "nickname"=>"Api::V1::Sample#update",
+              "consumes"=>["application/json", "text/xml"]
+            }
+          ]
+        }
+      ]
+      expect(declaration.apis).to eq(expected_apis_array)
+    end
+  end
+end