swagger-core 0.2.0 → 0.2.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 504f9a4a59a9375122f41ce9f860d4ba987794cf
+  data.tar.gz: 188dd67ba02fac3c733a576a446daba3b8328aa4
+SHA512:
+  metadata.gz: a9296b2964903801be8427af3f6a59e2a67c6fe8612c8be3c0bf634166584208d7732a0c8aeefcb10f3a6434114f4e34d8015a4eaa01bf08875ba3202bed678f
+  data.tar.gz: 7aea8b5d5d3f074fa856545d69b0c72b2d5d9d4df84c7b1c0c26e040e8cc81761411cf61e6835a7ff5c30cda0f92c6a5324149dc7e0634365f130c315fa707a3

data/.rspec

@@ -0,0 +1 @@
+--color

data/.rubocop.yml

@@ -7,6 +7,8 @@
 
 # Not yet...
 Style/Documentation:
+  # See https://github.com/bbatsov/rubocop/issues/947
+  # Use inch instead
   Enabled: false
 Style/Encoding:
   EnforcedStyle: when_needed

data/.yardopts

@@ -0,0 +1,4 @@
+--no-private
+lib/swagger/definition_section.rb
+lib/swagger.rb
+lib/**/*.rb

data/Gemfile

@@ -2,3 +2,4 @@ source 'https://rubygems.org'
 
 # Specify your gem's dependencies in swagger.gemspec
 gemspec
+gem 'pry'

data/README.md

@@ -1,13 +1,15 @@
 # Swagger
 
-TODO: Write a gem description
+Swagger is a Ruby library for parsing, building, and traversing (Swagger)[http://swagger.io/] API definitions.
 
 ## Installation
 
+*NOTE*: The gem is named `swagger-core`, because `swagger` was taken by an unrelated project.
+
 Add this line to your application's Gemfile:
 
 ```ruby
-gem 'swagger'
+gem 'swagger-core'
 ```
 
 And then execute:
@@ -16,11 +18,92 @@ And then execute:
 
 Or install it yourself as:
 
-    $ gem install swagger
+    $ gem install swagger-core
+
+## Features
+
+- Structural and semantic validation of Swagger objects
+- Convenient traversal APIs: use hierarchical or flat traversals
+- Handles derived or combined properties, like joining root, path, and operation level property definitions
+- A Swagger::Builder to help create valid Swagger documents from other data
 
 ## Usage
 
-TODO: Write usage instructions here
+### Parsing
+
+If you're loading a Swagger document from a file, you can use `#load`. The Swagger version will be detected from the file content.
+
+```ruby
+api = Swagger.load('swagger.yaml')
+```
+
+If you already have the Swagger content loaded as a Hash you can call build, or you can call
+build and tell Swagger the content is a JSON or YAML string it needs to parse.
+
+```ruby
+api = Swagger.build(hash)
+# or
+api = Swagger.build(json, format: :json)
+# or
+api = Swagger.build(yaml, format: :yaml)
+```
+
+### Traversing
+
+The parsing methods above all return an API object. The object has a hierarchical object that mirrors the Swagger specification. You can traverse it hierarchically, for example:
+
+```ruby
+api.paths['/pets'].get
+# {"tags"=>["Pet Operations"],
+# "summary"=>"finds pets in the system",
+# "responses"=>
+  {"200"=>{"description"=>"pet response", "schema"=>{"type"=>"array", "items"=>{"$ref"=>"#/definitions/Pet"}}, "headers"=>[{"x-expires"=>{"type"=>"string"}}]},
+   "default"=>{"description"=>"unexpected error", "schema"=>{"$ref"=>"#/definitions/Error"}}}}
+```
+
+There are also methods available to provide flatter APIs or convenient derived properties. For example:
+
+```ruby
+api.operations.each do | operation |
+  puts operation.signature
+end
+# GET petstore.swagger.wordnik.com/api/pets
+# POST petstore.swagger.wordnik.com/api/pets
+# GET petstore.swagger.wordnik.com/api/pets/{id}
+# DELETE petstore.swagger.wordnik.com/api/pets/{id}
+```
+
+See the RDoc documentation for more details.
+
+### Building
+
+If you want to build a Swagger document from another structure, you can use the builder. It will validate the structure and data types as you build the Swagger document, but it won't enforce constraints about required Swagger fields until you call `Swagger::Builder#build`.
+
+```ruby
+builder = Swagger.builder
+# or builder = Swagger.builder(version: '2.0')
+
+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
+
+api = builder.build
+```
+
+## TODO
+
+* Support Swagger 1.2 - right now only Swagger 2.0 is supported
+* Better handling of $ref
+* Handle combined parameters, respones, etc
 
 ## Contributing
 

data/Rakefile

@@ -1,8 +1,11 @@
 require 'bundler/gem_tasks'
 require 'rspec/core/rake_task'
 require 'rubocop/rake_task'
+require 'rake/notes/rake_task'
+require 'inch/rake'
 
 RSpec::Core::RakeTask.new(:spec)
 RuboCop::RakeTask.new
+Inch::Rake::Suggest.new
 
-task default: [:spec, :rubocop]
+task default: [:spec, :rubocop, :notes]

data/lib/swagger.rb

@@ -3,6 +3,8 @@ require 'addressable/uri'
 require 'addressable/template'
 require 'hashie'
 
+# Provides loading and building capabilities for Swagger.
+# @see http://swagger.io Swagger
 module Swagger
   RESOURCES_DIR = File.expand_path '../../resources/', __FILE__
   class InvalidDefinition < StandardError
@@ -11,20 +13,42 @@ module Swagger
       super("The Swagger definition is invalid. The following errors were detected: #{errors.inspect}")
     end
   end
+  # Instantiates a Swagger::API from the content.
+  # @param [Hash] opts the build options
+  # @option opts [String] :version the target Swagger specification version
+  # @returns [API]
+  def self.build(content, opts = {})
+    parser ||= Swagger::Parsers.parser_for(opts[:format])
+    content = parser.parse(content) unless parser.nil?
+    Swagger::API.build(content)
+  end
 
-  def self.load(file, loader = nil)
+  # Load a Swagger document from a file.
+  # @param [Hash] opts the load options
+  # @option opts [String] :format the format (yaml or json). Detected by file extension if omitted.
+  # @returns [API] a Swagger API object
+  def self.load(file, opts = {})
     ext = File.extname file
-    loader ||= Swagger::Loaders.loader_for ext
-    loader.load File.read(file)
+    opts[:format] = ext
+    content = File.read(file)
+    build(content, opts)
+  end
+
+  # Creates a Swagger::Builder that can be used to create a Swagger document.
+  # @param [Hash] opts the build options
+  # @option opts [String] :version the target Swagger specification version
+  # @returns Swagger::Builder
+  def self.builder(opts = {})
+    Swagger::Builder.builder(opts)
   end
 end
 
 require 'swagger/attachable'
-require 'swagger/definition_section'
+require 'swagger/swagger_object'
 require 'swagger/schema'
 require 'swagger/uri'
 require 'swagger/uri_template'
-require 'swagger/loaders'
+require 'swagger/parsers'
 require 'swagger/mime_type'
-require 'swagger/api_declaration'
+require 'swagger/api'
 require 'swagger/builder'

data/lib/swagger/{api_declaration.rb → api.rb}

@@ -1,11 +1,12 @@
 module Swagger
-  class APIDeclaration < DefinitionSection
+  # A common interface for building or loading Swagger documents of any version. See subclasses.
+  class API < SwaggerObject
     def self.build(hash)
       version = hash['swaggerVersion'] || hash['swagger']
       major, _minor = version.to_s.split('.')
       case major
       when '2'
-        Swagger::V2::APIDeclaration.new hash
+        Swagger::V2::API.new hash
       else
         fail ArgumentError, "Swagger version #{version} is not currently supported"
       end
@@ -22,4 +23,4 @@ module Swagger
   end
 end
 
-require 'swagger/v2/api_declaration'
+require 'swagger/v2/api'

data/lib/swagger/attachable.rb

@@ -1,5 +1,13 @@
 module Swagger
+  # A module that attaches parent objects to their children so you can navigate back
+  # up the hierarchy.
   module Attachable
+    # The top-level object in the hierarchy.
+    def root
+      return self if parent.nil?
+      parent.root
+    end
+
     # @api private
     def attach_parent(parent)
       @parent = parent
@@ -22,10 +30,5 @@ module Swagger
         end
       end
     end
-
-    def root
-      return self if parent.nil?
-      parent.root
-    end
   end
 end

data/lib/swagger/builder.rb

@@ -5,6 +5,7 @@ module Swagger
   # the same rules as a Dash except for 'required' properties,
   # which are not enforced until converting to a Dash via `build`.
   module Bash
+    # @api private
     module ClassMethods
       def self.extend_object(dash)
         fail TypeError, 'Bash only works on Dash' unless dash <= Hashie::Dash
@@ -17,6 +18,7 @@ module Swagger
       end
     end
 
+    # @api private
     def self.included(dash) # rubocop:disable Metrics/MethodLength
       fail TypeError, 'Bash only works on Dash' unless dash <= Hashie::Dash
       dash.extend ClassMethods
@@ -81,7 +83,27 @@ module Swagger
     end
   end
 
-  class Builder < Swagger::V2::APIDeclaration
-    include Swagger::Bash
+  # An object for building a Swagger document. Coerces and validates data types
+  # as create the document, but does not enforce required fields until you call
+  # #{Bash#build}.
+  module Builder
+    def self.builder(opts = {})
+      version = opts[:version] || '2.0'
+      target_class = target_api_class(version)
+      klass = Swagger::Bash.infect(target_class)
+      klass.new({})
+    end
+
+    private
+
+    def self.target_api_class(version)
+      major, _minor = version.to_s.split('.')
+      case major
+      when '2'
+        Swagger::V2::API
+      else
+        fail ArgumentError, "Swagger version #{version} is not currently supported"
+      end
+    end
   end
 end

data/lib/swagger/mime_type.rb

@@ -1,12 +1,22 @@
 require 'mime/types'
 
 module Swagger
+  # Class representing Media Types (commonly known as MIME Types).
+  # @see http://en.wikipedia.org/wiki/Internet_media_type
   class MimeType < String
     extend Forwardable
     def_delegators :@mime_type, :media_type, :sub_type
 
     MIME_TYPE_FORMAT = /(\w+)\/(\w+\.)?([\w\.]+)(\+\w+)?\s*(;.*)?/
 
+    COMMON_ALIASES = {
+      txt:    'text/plain',
+      text:   'text/plain',
+      json:   'application/json',
+      xml:    'application/xml',
+      binary: 'application/octet-stream'
+    }
+
     def initialize(mime_type_name)
       @mime_type_name = mime_type_name.to_s
       @mime_type = MIME::Types[@mime_type_name].first || base_type(@mime_type_name)
@@ -14,6 +24,16 @@ module Swagger
       super @mime_type_name
     end
 
+    def self.parser_for(mime_type)
+      mime_type = COMMON_ALIASES[mime_type] if COMMON_ALIASES.key? mime_type
+      case mime_type
+      when 'application/json'
+        return JSON
+      else
+        fail NotImplementedError, "Parser support for #{mime_type} is not implemented"
+      end
+    end
+
     private
 
     def base_type(mime_type_name)

data/lib/swagger/parsers.rb

@@ -0,0 +1,38 @@
+autoload :YAML, 'yaml'
+autoload :JSON, 'json'
+
+module Swagger
+  # Provides classes for loading Swagger from YAML or JSON.
+  module Parsers
+    def self.parser_for(format)
+      case format
+      when '.yaml', '.yml', :yaml
+        YAMLParser
+      when '.json', '.js', :json
+        JSONParser
+      else
+        nil
+      end
+    end
+
+    # Parses YAML content
+    class YAMLParser
+      # Parses a YAML document
+      # @param content [String] The YAML content to parse
+      # @return [Hash] the parsed content
+      def self.parse(content)
+        YAML.load(content)
+      end
+    end
+
+    # Parses JSON content
+    class JSONParser
+      # Parses a JSON document
+      # @param content [String] The JSON content to parse
+      # @return [Hash] the parsed content
+      def self.parse(content)
+        JSON.parse(content)
+      end
+    end
+  end
+end

data/lib/swagger/schema.rb

@@ -1,4 +1,7 @@
 module Swagger
+  # Represents a Swagger Schema Object, a more deterministic subset of JSON Schema.
+  # @see https://github.com/wordnik/swagger-spec/blob/master/versions/2.0.md#schema-object- Schema Object
+  # @see http://json-schema.org/ JSON Schema
   class Schema < Hashie::Mash
     include Attachable
     include Hashie::Extensions::MergeInitializer

data/lib/swagger/swagger_object.rb

@@ -0,0 +1,42 @@
+module Swagger
+  # A class that represents an Object defined in the Swagger specification.
+  # Provides methods for defining fields in the object.
+  class SwaggerObject < Hashie::Dash
+    include Hashie::Extensions::Coercion
+    include Hashie::Extensions::IndifferentAccess
+    include Swagger::Attachable
+
+    attr_accessor :parent
+
+    # @api private
+    # Initializes a Swagger object, using Hashie::Dash,
+    # and attaches to children objects so navigation via +parent+
+    # and +root+ is possible.
+    def initialize(hash)
+      super
+      attach_to_children
+    end
+
+    # @api private
+    # @!macro [attach] field
+    #   @!attribute [rw] $1
+    #     Swagger field $1. $3
+    #     @return [$2]
+    # Defines a Swagger field on a class.
+    def self.field(name, type, opts = {})
+      property name, opts
+      coerce_key name, type
+    end
+
+    # @api private
+    # @!macro [attach] required_field
+    #   @!attribute [rw] $1
+    #     **Required** Swagger field $1. $3
+    #     @return [$2]
+    # Defines a required Swagger field on a class.
+    def self.required_field(name, type, opts = {})
+      opts[:required] = true
+      field(name, type, opts)
+    end
+  end
+end

data/lib/swagger/uri.rb

@@ -1,8 +1,9 @@
 module Swagger
+  # Class representing a URI. Backed by Addressable::URI.
+  # @see http://en.wikipedia.org/wiki/Uniform_resource_identifier
   class URI < String
     attr_reader :uri
     def initialize(string)
-      # FIXME: Is it possible to initialize with heuristic parse once?
       @uri = Addressable::URI.heuristic_parse string
       super
     end