swagger-blocks 0.0.1 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: b309bb304d3b80b0a6e213b7f3ec59ae1c9fa51a
-  data.tar.gz: c68fce426638012787fc21ea5f6ee4c514ae4d18
+  metadata.gz: 1feb49d6ff4f98fa20993ea31858e263c5ce09a4
+  data.tar.gz: 202eb893193d3bad7599791c72014d0f06a0a045
 SHA512:
-  metadata.gz: f4d95e4aedf7c8107d2c09e4c814cdc59c7336e5fb4370e345055fc01de0b7807787d74ca9f6250d4a5f7d6182adb3f7ef0252fe598171c7332d0dfa9490828c
-  data.tar.gz: f419056f5dd26c88d8dafd5f1fcbff859015257897db939ff1d46e13f97e481020362c2db6c948b35a8c80f3a9deb7d6bc21212d262fcdde88c546f5df6e9d10
+  metadata.gz: b11d4343fa07338eb7706960b9aa0e1e2714b4abd46948d894e42a7ff2deb93bfbc9b6d38db61896d4d3bebccda52995b85f71a8ec23c4502d0c2297f41e1f68
+  data.tar.gz: 83bc75e151706a81535523a9a7b797c45943324a50ee913ed35c62f2453ddf8d8beaaf950c7ab5a1c9d8f1b1557a5885de2094ae5c9609bb9f6d16064c00ea2e

data/README.md

@@ -2,25 +2,171 @@
 
 [![Build Status](https://travis-ci.org/fotinakis/swagger-blocks.svg?branch=master)](https://travis-ci.org/fotinakis/swagger-blocks)
 
-TODO: Write a gem description
+Swagger::Blocks is a DSL for pure Ruby code blocks that can be turned into JSON.
+
+It helps you write API docs in the [Swagger](https://helloreverb.com/developers/swagger) style in Ruby and then automatically build JSON that is compatible with [Swagger UI](http://petstore.swagger.wordnik.com/#!/pet).
+
+## Features
+
+* Supports **live updating** by design. Change code, refresh your API docs.
+* **Works with all Ruby web frameworks** including Rails, Sinatra, etc.
+* **100% support** for all features of the [Swagger 1.2 spec](https://github.com/wordnik/swagger-spec/blob/master/versions/1.2.md).
+* Flexible—you can use Swagger::Blocks anywhere, split up blocks to fit your style preferences, etc. Since it's pure Ruby and serves definitions dynamically, you can easily use initializers/config objects to change values or even show/hide different APIs based on environment.
+* 1:1 naming with the Swagger spec—block names and nesting should match almost exactly with the swagger spec, with rare exceptions to make things more convenient.
 
 ## Installation
 
 Add this line to your application's Gemfile:
 
     gem 'swagger-blocks'
+    
+Or install directly with `gem install swagger-blocks`. **Requires Ruby 2.1+**
+
+## Example (Rails)
+
+This is a simplified example based on the objects in the Petstore [Swagger Sample App](http://petstore.swagger.wordnik.com/#!/pet). For a more complex and complete example, see the [swagger_blocks_spec.rb](https://github.com/fotinakis/swagger-blocks/blob/master/spec/lib/swagger_blocks_spec.rb) file.
+
+Also note that Rails is not required, you can use Swagger::Blocks with any Ruby web framework.
+
+#### PetsController
+
+Parameters and features below are defined by the [Swagger 1.2 spec](https://github.com/wordnik/swagger-spec/blob/master/versions/1.2.md).
+
+```Ruby
+class PetsController < ActionController::Base
+  include Swagger::Blocks
+
+  swagger_api_root :pets do
+    key :swaggerVersion, '1.2'
+    key :apiVersion, '1.0.0'
+    key :basePath, 'http://petstore.swagger.wordnik.com/api'
+    key :resourcePath, '/pets'
+    api do
+      key :path, '/pets/{petId}'
+      operation do
+        key :method, 'GET'
+        key :summary, 'Find pet by ID'
+        key :notes, 'Returns a pet based on ID'
+        key :type, :Pet
+        key :nickname, :getPetById
+        parameter do
+          key :paramType, :path
+          key :name, :petId
+          key :description, 'ID of pet that needs to be fetched'
+          key :required, true
+          key :type, :integer
+        end
+        response_message do
+          key :code, 400
+          key :message, 'Invalid ID supplied'
+        end
+        response_message do
+          key :code, 404
+          key :message, 'Pet not found'
+        end
+      end
+    end
+  end
+  
+  # ...
+end
+```
+
+#### Pet model
+
+```Ruby
+class Pet < ActiveRecord::Base
+  include Swagger::Blocks
 
-And then execute:
+  swagger_model :Pet do
+    key :id, :Pet
+    key :required, [:id, :name]
+    property :id do
+      key :type, :integer
+      key :format, :int64
+      key :description, 'unique identifier for the pet'
+      key :minimum, '0.0'
+      key :maximum, '100.0'
+    end
+    property :name do
+      key :type, :string
+    end
+    property :photoUrls do
+      key :type, :array
+      items do
+        key :type, :string
+      end
+    end
+    property :status do
+      key :type, :string
+      key :description, 'pet status in the store'
+      key :enum, [:available, :pending, :sold]
+    end
+  end
+  
+  # ...
+end
+```
 
-    $ bundle
+#### Docs controller
 
-Or install it yourself as:
+To integrate these definitions with Swagger UI, we need a docs controller that can serve the JSON definitions.
 
-    $ gem install swagger-blocks
+```Ruby
+resources :apidocs, only: [:index, :show]
+```
 
-## Usage
+```Ruby
+class ApidocsController < ActionController::Base
+  include Swagger::Blocks
 
-TODO: Write usage instructions here
+  swagger_root do
+    key :swaggerVersion, '1.2'
+    key :apiVersion, '1.0.0'
+    info do
+      key :title, 'Swagger Sample App'
+    end
+    api do
+      key :path, '/pets'
+      key :description, 'Operations about pets'
+    end
+  end
+  
+  # A list of all classes that have swagger_* declarations.
+  SWAGGERED_CLASSES = [
+    PetsController,
+    Pets,
+    self,
+  ].freeze
+  
+  def index
+    render json: Swagger::Blocks.build_root_json(SWAGGERED_CLASSES)
+  end
+
+  def show
+    render json: Swagger::Blocks.build_api_json(params[:id], SWAGGERED_CLASSES)
+  end
+end
+
+```
+
+The special part of this controller are these lines:
+
+```Ruby
+render json: Swagger::Blocks.build_root_json(SWAGGERED_CLASSES)
+```
+
+```Ruby
+render json: Swagger::Blocks.build_api_json(params[:id], SWAGGERED_CLASSES)
+```
+
+Those are the only lines necessary to build the root Swagger [Resource Listing](https://github.com/wordnik/swagger-spec/blob/master/versions/1.2.md#51-resource-listing) JSON and the JSON for each Swagger [API Declaration](https://github.com/wordnik/swagger-spec/blob/master/versions/1.2.md#52-api-declaration). You simply pass in a list of all the "swaggered" classes in your app.
+
+Now, simply point Swagger UI at `/apidocs` and everything should Just Work™. If you change any of the Swagger block definitions, you can simply refresh Swagger UI to see the changes.
+
+## Reference
+
+See the [swagger_blocks_spec.rb](https://github.com/fotinakis/swagger-blocks/blob/master/spec/lib/swagger_blocks_spec.rb) for examples of more complex features and declarations possible.
 
 ## Contributing
 
@@ -29,3 +175,7 @@ TODO: Write usage instructions here
 3. Commit your changes (`git commit -am 'Add some feature'`)
 4. Push to the branch (`git push origin my-new-feature`)
 5. Create a new Pull Request
+
+## Credits
+
+Original idea inspired by **[@richhollis](https://github.com/richhollis/)**'s [swagger-docs](https://github.com/richhollis/swagger-docs/) gem.

data/lib/swagger/blocks/version.rb

@@ -1,5 +1,5 @@
 module Swagger
   module Blocks
-    VERSION = '0.0.1'
+    VERSION = '1.0.0'
   end
 end

data/swagger-blocks.gemspec

@@ -8,7 +8,7 @@ Gem::Specification.new do |spec|
   spec.version       = Swagger::Blocks::VERSION
   spec.authors       = ['Mike Fotinakis']
   spec.email         = ['mike@fotinakis.com']
-  spec.summary       = %q{Define and generate Swagger JSON files in Ruby.}
+  spec.summary       = %q{Define and serve live-updating Swagger JSON for Ruby apps.}
   spec.description   = %q{}
   spec.homepage      = 'https://github.com/fotinakis/swagger-blocks'
   spec.license       = 'MIT'
@@ -17,6 +17,7 @@ Gem::Specification.new do |spec|
   spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
   spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
   spec.require_paths = ['lib']
+  spec.required_ruby_version = '>= 2.1'
 
   spec.add_development_dependency 'bundler'
   spec.add_development_dependency 'rake'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: swagger-blocks
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 1.0.0
 platform: ruby
 authors:
 - Mike Fotinakis
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-09-07 00:00:00.000000000 Z
+date: 2015-01-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -99,7 +99,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: '2.1'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
@@ -107,10 +107,10 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.4.1
+rubygems_version: 2.2.2
 signing_key: 
 specification_version: 4
-summary: Define and generate Swagger JSON files in Ruby.
+summary: Define and serve live-updating Swagger JSON for Ruby apps.
 test_files:
 - spec/lib/swagger_api_declaration.json
 - spec/lib/swagger_blocks_spec.rb