swagger-core 0.2.0 → 0.2.1

data/lib/swagger/uri_template.rb

@@ -1,9 +1,10 @@
 module Swagger
+  # Class representing a URI Template. Backed by Addressable::Template.
+  # @see http://tools.ietf.org/html/rfc6570
   class URITemplate < String
     attr_reader :uri_template
     def initialize(string)
-      # FIXME: Is it possible to initialize with heuristic parse once?
-      @uri_template = Addressable::Template.new string
+      @uri_template = Addressable::Template.new(string)
       super
     end
   end

data/lib/swagger/v2/api.rb

@@ -0,0 +1,89 @@
+require 'swagger/swagger_object'
+require 'swagger/v2/info'
+require 'swagger/v2/path'
+require 'swagger/v2/tag'
+require 'json-schema'
+
+module Swagger
+  # Module containing classes that handle version 2 of the Swagger specification.
+  # @see https://github.com/wordnik/swagger-spec/blob/master/versions/2.0.md Swagger Specification 2.0
+  module V2
+    SWAGGER_SCHEMA = File.expand_path 'schemas/swagger/v2.0/schema.json', Swagger::RESOURCES_DIR
+    JSON_SCHEMA = File.expand_path 'schemas/json_schema/draft-04.json', Swagger::RESOURCES_DIR
+
+    # Class representing the top level "Swagger Object"
+    # @see https://github.com/wordnik/swagger-spec/blob/master/versions/2.0.md#swagger-object- Swagger Object
+    class API < Swagger::API
+      # @group Swagger Fields
+      # HACK: Swagger-Spec: This is correct for now, but schema will likely be changed to String
+      required_field :swagger, Float
+      required_field :info, Info
+      field :host, Swagger::URITemplate
+      field :basePath, Swagger::URITemplate
+      field :schemes, Array[String]
+      field :consumes, Array[String]
+      field :produces, Array[String]
+      required_field :paths, Hash[String => Path]
+      field :definitions, Hash[String => Schema]
+      field :parameters, Hash[String => Parameter]
+      field :responses, Hash[String => Response]
+      # HACK: Swagger-Spec: Not documented/defined yet. Implement once spec is complete.
+      field :security, Object
+      # TODO: This is actually an array of tag names, not Tag objects, need to handle relation
+      field :tag, Array[String]
+      # TODO: externalDocs - Documentable Module
+      # @endgroup
+
+      alias_method :base_path, :basePath
+
+      # All operations under all paths
+      # @return [Array<Operation>]
+      def operations
+        # Perhaps not the best way...
+        paths.values.map do | path |
+          path.operations.values
+        end.flatten
+      end
+
+      # A complete (including host) URI Template for the basePath.
+      # @return [Swagger::URITemplate]
+      def uri_template
+        Swagger::URITemplate.new("#{host}#{basePath}")
+      end
+
+      # Validates this object against the Swagger specification and returns all detected errors.
+      # Slower than {#validate}.
+      # @return [true] if the object fully complies with the Swagger specification.
+      # @raise [Swagger::InvalidDefinition] if any errors are found.
+      def fully_validate
+        # NOTE: fully_validate is ideal, but very slow with the current schema/validator
+        errors = JSON::Validator.fully_validate(swagger_schema, to_json)
+        fail Swagger::InvalidDefinition, errors unless errors.empty?
+        true
+      end
+
+      # Validates this object against the Swagger specification and returns the first detected error.
+      # Faster than {#fully_validate}.
+      # @return [true] if the object fully complies with the Swagger specification.
+      # @raise [Swagger::InvalidDefinition] if an error is found.
+      def validate
+        JSON::Validator.validate!(swagger_schema, to_json)
+      rescue JSON::Schema::ValidationError => e
+        raise Swagger::InvalidDefinition, e.message
+      end
+
+      private
+
+      def swagger_schema
+        @swagger_schema ||= JSON.parse(File.read(SWAGGER_SCHEMA))
+
+        # FIXME: Swagger should be able to parse offline. Blocked by json-schema.
+        # Offline workaround
+        # @swagger_schema = JSON.parse(File.read(SWAGGER_SCHEMA)
+        #   .gsub('http://json-schema.org/draft-04/schema', "file://#{SWAGGER_SCHEMA}"))
+        # @swagger_schema['$schema'] = 'http://json-schema.org/draft-04/schema#'
+        # @swagger_schema
+      end
+    end
+  end
+end

data/lib/swagger/v2/example.rb

@@ -1,19 +1,27 @@
 module Swagger
   module V2
+    # A class to represent example objects in the Swagger schema.
+    # Usually used to represent example request or responses.
+    # Provides access to both the raw example or a parsed representation.
     class Example
       extend Forwardable
       def_delegator :@raw, :to_s, :inspect
 
+      # The example as it appears in the Swagger document.
+      # @return Object the example
       attr_reader :raw
 
       def initialize(sample)
         @raw = sample
       end
 
-      def parse(_format = :json)
+      # The example after it has been parsed to match the +media_type+.
+      # @param media_type [String] the target media_type
+      # @return [Object] an object according to the +media_type+
+      def parse(media_type = 'application/json')
         return @raw unless @raw.is_a? String
-
-        JSON.parse(@raw)
+        parser = Swagger::MIMEType.parser_for(media_type)
+        parser.parse(@raw)
       end
 
       def inspect

data/lib/swagger/v2/info.rb

@@ -1,23 +1,33 @@
+require 'swagger/swagger_object'
+
 module Swagger
   module V2
-    class Info < DefinitionSection
-      class Contact < DefinitionSection
-        section :name, String
-        section :url, Swagger::URI
-        section :email, String
+    # Class representing a Swagger "Info Object".
+    # @see https://github.com/wordnik/swagger-spec/blob/master/versions/2.0.md#infoObject Info Object
+    class Info < SwaggerObject
+      # Class representing a Swagger "Contact Object".
+      # @see https://github.com/wordnik/swagger-spec/blob/master/versions/2.0.md#contactObject Contact Object
+      class Contact < SwaggerObject
+        # @group Swagger Fields
+        field :name, String
+        field :url, Swagger::URI
+        field :email, String
+        # @endgroup
       end
 
-      class License < DefinitionSection
-        required_section :name, String
-        section :url, Swagger::URI
+      # Class representing a Swagger "License Object".
+      # @see https://github.com/wordnik/swagger-spec/blob/master/versions/2.0.md#licenseObject License Object
+      class License < SwaggerObject
+        required_field :name, String
+        field :url, Swagger::URI
       end
 
-      required_section :version, String
-      required_section :title, String
-      section :description, String
-      section :termsOfService, String
-      section :contact, Contact
-      section :license, License
+      required_field :title, String
+      field :description, String
+      field :termsOfService, String
+      field :contact, Contact
+      field :license, License
+      required_field :version, String
     end
   end
 end

data/lib/swagger/v2/operation.rb

@@ -0,0 +1,52 @@
+require 'swagger/swagger_object'
+require 'swagger/v2/parameter'
+require 'swagger/v2/response'
+
+module Swagger
+  module V2
+    # Class representing a Swagger "Operation Object".
+    # @see https://github.com/wordnik/swagger-spec/blob/master/versions/2.0.md#operationObject Operation Object
+    class Operation < SwaggerObject
+      extend Forwardable
+      def_delegators :parent, :uri_template, :path, :host
+
+      # required_field :verb, Symbol
+      field :summary, String
+      field :description, String
+      field :operationId, String
+      alias_method :operation_id, :operationId
+      field :produces, Array[String]
+      field :consumes, Array[String]
+      field :tags, Array[String]
+      field :parameters, Array[Parameter]
+      field :responses, Hash[String => Response]
+      field :schemes, Array[String]
+
+      # TODO: Add externalDocs
+
+      def api_title
+        root.info.title
+      end
+
+      def full_name
+        "#{api_title} - #{summary}"
+      end
+
+      def verb
+        parent.operations.key self
+      end
+
+      def signature
+        "#{verb.to_s.upcase} #{parent.uri_template}"
+      end
+
+      def default_response
+        return nil if responses.values.nil?
+
+        # FIXME: Swagger isn't very clear on "normal response codes"
+        # In the examples, default is actually an error
+        responses['200'] || responses['201'] || responses['default'] || responses.values.first
+      end
+    end
+  end
+end

data/lib/swagger/v2/parameter.rb

@@ -1,6 +1,45 @@
+require 'swagger/swagger_object'
+
 module Swagger
   module V2
-    class Parameter < Hashie::Mash
+    # Class representing a Swagger "Parameter Object".
+    # @see https://github.com/wordnik/swagger-spec/blob/master/versions/2.0.md#parameterObject Parameter Object
+    class Parameter < SwaggerObject
+      # @!group Fixed Fields
+      required_field :name, String
+      # required_field :in, String
+      field :in, String
+      field :description, String
+      field :required, Object # FIXME: Should be a boolean
+      # @!endgroup
+
+      # @!group Body Fields
+      field :schema, Schema
+      # @!endgroup
+
+      # @!group Non-Body Fields
+      field :type, String
+      field :format, String
+      field :items, Hash # TODO: Items Object
+      field :collectionFormat, String
+      field :default, Object
+      # @!endgroup
+
+      # @!group Deterministic JSON Schema
+      field :default, Object
+      field :maximum, Numeric
+      field :exclusiveMaximum, String # FIXME: boolean
+      field :minimum, Numeric
+      field :exclusiveMinimum,  String # FIXME: boolean
+      field :maxLength, Integer
+      field :minLength, Integer
+      field :pattern, String
+      field :maxItems,  Integer
+      field :minItems,  Integer
+      field :uniqueItems, String # FIXME: boolean
+      field :enum,  Array[Object]
+      field :multipleOf,  Numeric
+      # @!endgroup
     end
   end
 end

data/lib/swagger/v2/path.rb

@@ -1,18 +1,19 @@
-require 'swagger/v2/api_operation'
+require 'swagger/swagger_object'
+require 'swagger/v2/operation'
 
 module Swagger
   module V2
-    class Path < DefinitionSection
+    # Class representing a Swagger "Path Item Object".
+    # @see https://github.com/wordnik/swagger-spec/blob/master/versions/2.0.md#pathItemObject Path Item Object
+    class Path < SwaggerObject
       extend Forwardable
       def_delegator :parent, :host
 
       VERBS = [:get, :put, :post, :delete, :options, :head, :patch]
-
-      section :parameters, Array[Parameter]
-
       VERBS.each do | verb |
-        section verb, APIOperation
+        field verb, Operation
       end
+      field :parameters, Array[Parameter]
 
       def initialize(hash)
         hash[:parameters] ||= []

data/lib/swagger/v2/response.rb

@@ -1,14 +1,18 @@
+require 'swagger/swagger_object'
 require 'swagger/v2/example'
 
 module Swagger
   module V2
-    class Response < DefinitionSection
-      section :description, String
-      section :schema, Swagger::Schema
-      section :headers, Array # [String => String] # TODO: Headers
-      section :examples, Hash[Swagger::MimeType => Example]
+    # Class representing a Swagger "Response Object".
+    # @see https://github.com/wordnik/swagger-spec/blob/master/versions/2.0.md#responseObject Response Object
+    class Response < SwaggerObject
+      field :description, String
+      field :schema, Swagger::Schema
+      field :headers, Array # [String => String] # TODO: Headers
+      field :examples, Hash[Swagger::MimeType => Example]
 
       def status_code
+        # FIXME: swagger-spec needs a defined way to define codes
         code = parent.responses.key self
         code = '200' if code == 'default'
         code.to_i

data/lib/swagger/v2/tag.rb

@@ -0,0 +1,11 @@
+module Swagger
+  module V2
+    # Class representing a Swagger "Tag Object".
+    # @see https://github.com/wordnik/swagger-spec/blob/master/versions/2.0.md#tagObject Tag Object
+    class Tag < SwaggerObject
+      required_field :name, String
+      field :description, String
+      # TODO: Documentable
+    end
+  end
+end

data/lib/swagger/version.rb

@@ -1,3 +1,3 @@
 module Swagger
-  VERSION = '0.2.0'
+  VERSION = '0.2.1'
 end

data/resources/schemas/swagger/v2.0/schema.json

@@ -62,7 +62,7 @@
         "^x-": {
           "$ref": "#/definitions/vendorExtension"
         },
-        "^/.*[^\/]$": {
+        "^\/$|^\/.*[^\/]$": {
           "$ref": "#/definitions/pathItem"
         }
       },
@@ -523,7 +523,7 @@
         "^x-": {
           "$ref": "#/definitions/vendorExtension"
         },
-        "^/.*[^\/]$": {
+        "^\/$|^\/.*[^\/]$": {
           "type": "string"
         }
       }

data/spec/swagger/{api_declaration_spec.rb → api_spec.rb}

@@ -2,7 +2,7 @@ require 'spec_helper'
 
 module Swagger
   module V2
-    describe APIDeclaration do
+    describe API do
       let(:swagger_file) { 'spec/fixtures/petstore-full.yaml' }
       let(:swagger) { Swagger.load swagger_file }
       let(:expected_host) { 'petstore.swagger.wordnik.com' }

data/spec/swagger/builder_spec.rb

@@ -0,0 +1,52 @@
+require 'spec_helper'
+
+module Swagger
+  describe Builder do
+    subject(:builder) { described_class.builder }
+    describe 'setting fields' do
+      it 'raises an error if the field does not exist' do
+        expect { builder.xxx = 'foo' }.to raise_error(NoMethodError)
+      end
+
+      it 'raises if the value cannot be coerced to match the field' do
+        expect { builder.swagger = :foo }.to raise_error(Hashie::CoercionError)
+      end
+
+      it 'sets the field' do
+        expect { builder.swagger = 2.0 }.to change { builder.swagger }.from(nil).to(2.0)
+      end
+
+      it 'allows complex types to be set via a block' do
+        builder.info do |info|
+          info.title = 'Sample Swagger API'
+          info.version = '1.0'
+        end
+
+        expect(builder.info).to be_an_kind_of(Swagger::Bash)
+        expect(builder.info.title).to eq('Sample Swagger API')
+      end
+    end
+
+    describe '#build' do
+      it 'raises an error if a required field is omitted' do
+        expect { builder.build }.to raise_error(ArgumentError, /property '\w+' is required/)
+      end
+
+      it 'returns the built Swagger API object if all required fields are present' do
+        builder.swagger = 2.0
+        builder.info do |info|
+          info.title = 'Sample Swagger API'
+          info.version = '1.0'
+        end
+        builder.paths = {
+          '/foo' => {}
+        }
+        builder.paths['/foo'].get do |get|
+          get.description = 'Testing...'
+          get.tags = %w(foo bar)
+        end
+        expect(builder.build).to be_an_instance_of(Swagger::V2::API)
+      end
+    end
+  end
+end

data/spec/swagger/{api_operation_spec.rb → operation_spec.rb}

@@ -2,7 +2,7 @@ require 'spec_helper'
 
 module Swagger
   module V2
-    describe APIOperation do
+    describe Operation do
       context 'Sample petstore API' do
         let(:swagger_file) { 'spec/fixtures/petstore-full.yaml' }
         let(:swagger) { Swagger.load swagger_file }
@@ -85,6 +85,14 @@ module Swagger
             expect(subject.description).to eq('pet response')
           end
         end
+
+        describe '#signature' do
+          subject { swagger.paths['/pets'].get }
+          it 'is a signature similar to what would appear in logs or HTTP dumps' do
+            # FIXME: It's a bit weird to have host but not scheme... but Swagger allows multiple schemes
+            expect(subject.signature).to eq('GET petstore.swagger.wordnik.com/api/pets')
+          end
+        end
       end
     end
   end