swagger_yard-rails 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: c94696f2feaf6e856d6ea364376c58a27ee9a9ba
-  data.tar.gz: 08976e63e0846806c8c2c94303a1c7191fa882e0
+  metadata.gz: c9a3c7979e9094f3ae93147cf96f9d5911f4e76a
+  data.tar.gz: 6d3f96edd8d111b2a04e66dd92d89c65cdf15bde
 SHA512:
-  metadata.gz: 5c12fefc9e29ebc4e924f8734ae2559f98f013aea0b85743f1a7faa7c472417d1dfe141f6f684f253cd8a2250e6f2cf38d6dd1fe3a0e82545d31a3a435c18ba7
-  data.tar.gz: afc7e95748615318a546b666ffb913753d8bdc61792c6bb6122d5be293c81458f053e1ab3f81c6b43c41bfcb194fd734abc40f6a733c3628b1acbe1dfad6a631
+  metadata.gz: 824fd5b2ea22087dbd9bd1605d575ffab6ae34367dc437eb6506594c51c27ae6460a0cd8c2be0f689ec7d2ed524e52dd5542c91f2c4c9fc585e265d7b1124fb5
+  data.tar.gz: 77316e1bdc076df24a5a72dc9c62c7fe745ca2c99cc89306cef1f056abdc7244856d4b41d9d9884c24d9abe865267979c5df3126a96b4dae80870d837d486d83

data/CHANGELOG.md

@@ -1,4 +1,14 @@
-## SwaggerYard 0.2.0 -- 20-10-2015 ##
+# SwaggerYard-Rails Changelog
+
+## 0.3.0 -- 16-12-2015 ##
+
+* Don't clobber controller/model lookup paths in initializer if they have
+  already been set
+* Look up routes using the Rails router; allows DRYing routes by omitting @path
+  tags in most cases.
+* Fix `swagger:json` rake task
+
+## 0.2.0 -- 20-10-2015 ##
 
 * Support for Swagger's Spec v2
 
@@ -8,7 +18,7 @@
 
     *Tony Pitale <@tpitale>*
 
-## SwaggerYard 0.1.0 -- 15-10-2015 ##
+## 0.1.0 -- 15-10-2015 ##
 
 * Add Engine from SwaggerYard
 * Update specs to make requests of rails app

data/CODE_OF_CONDUCT.md

@@ -1,13 +1,24 @@
 # Contributor Code of Conduct
 
-As contributors and maintainers of this project, we pledge to respect all people who contribute through reporting issues, posting feature requests, updating documentation, submitting pull requests or patches, and other activities.
+As contributors and maintainers of this project, and in the interest of fostering an open and welcoming community, we pledge to respect all people who contribute through reporting issues, posting feature requests, updating documentation, submitting pull requests or patches, and other activities.
 
-We are committed to making participation in this project a harassment-free experience for everyone, regardless of level of experience, gender, gender identity and expression, sexual orientation, disability, personal appearance, body size, race, ethnicity, age, or religion.
+We are committed to making participation in this project a harassment-free experience for everyone, regardless of level of experience, gender, gender identity and expression, sexual orientation, disability, personal appearance, body size, race, ethnicity, age, religion, or nationality.
 
-Examples of unacceptable behavior by participants include the use of sexual language or imagery, derogatory comments or personal attacks, trolling, public or private harassment, insults, or other unprofessional conduct.
+Examples of unacceptable behavior by participants include:
 
-Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct. Project maintainers who do not follow the Code of Conduct may be removed from the project team.
+* The use of sexualized language or imagery
+* Personal attacks
+* Trolling or insulting/derogatory comments
+* Public or private harassment
+* Publishing other's private information, such as physical or electronic addresses, without explicit permission
+* Other unethical or unprofessional conduct
 
-Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by opening an issue or contacting one or more of the project maintainers.
+Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, or to ban temporarily or permanently any contributor for other behaviors that they deem inappropriate, threatening, offensive, or harmful.
 
-This Code of Conduct is adapted from the [Contributor Covenant](http://contributor-covenant.org), version 1.0.0, available at [http://contributor-covenant.org/version/1/0/0/](http://contributor-covenant.org/version/1/0/0/)
+By adopting this Code of Conduct, project maintainers commit themselves to fairly and consistently applying these principles to every aspect of managing this project. Project maintainers who do not follow or enforce the Code of Conduct may be permanently removed from the project team.
+
+This code of conduct applies both within project spaces and in public spaces when an individual is representing the project or its community.
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting a project maintainer at [INSERT EMAIL ADDRESS]. All complaints will be reviewed and investigated and will result in a response that is deemed necessary and appropriate to the circumstances. Maintainers are obligated to maintain confidentiality with regard to the reporter of an incident.
+
+This Code of Conduct is adapted from the [Contributor Covenant](http://contributor-covenant.org), version 1.3.0, available at [http://contributor-covenant.org/version/1/3/0/](http://contributor-covenant.org/version/1/3/0/)

data/README.md

@@ -49,16 +49,60 @@ in application.js:
 
 ### Configure SwaggerYard ###
 
+See [Getting Started] in the swagger_yard docs for details.
+
 ```ruby
 # config/initializers/swagger_yard.rb
 SwaggerYard.configure do |config|
-  # the rest of your configuration here
+  # your configuration here
+end
+```
+
+[Getting Started]: https://github.com/tpitale/swagger_yard#getting-started
+
+### Write YARD documentation ###
 
-  # where your swagger spec json will show up
-  config.swagger_spec_base_path = "http://localhost:3000/swagger/api"
+Write YARD documentation for your controllers and models as described in
+[SwaggerYard Usage].
+
+To include a controller in your swagger definition, add a `@resource` tag to the
+controller's class documentation.
+
+```ruby
+# @resource Pet
+class PetsController < ApplicationController
+  # ...
 end
 ```
 
+Once a controller has been tagged as a swagger resource, all public instance
+methods with docstrings will be candidates for inclusion as swagger apis, even
+if they don't include `@path` tags. `swagger_yard-rails` includes a
+[path discovery function] implementation that uses the Rails router to lookup
+paths, allowing `@path` tags to be omitted.
+
+`swagger_yard-rails` also provides a `@route` tag to indicate a named route
+to be connected to an api action.
+
+```ruby
+# config/routes.rb
+Dummy::Application.routes.draw do
+  get '/greet', to: 'hello#greeting', as: 'greeting'
+end
+```
+
+```ruby
+# @resource Hello
+class HelloController < ApplicationController
+  # @route greeting
+  def greeting
+  end
+end
+```
+
+[SwaggerYard Usage]: https://github.com/tpitale/swagger_yard#swaggeryard-usage
+[path discovery function]: https://github.com/tpitale/swagger_yard#path-discovery-function
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.

data/lib/swagger_yard/rails.rb

@@ -7,3 +7,4 @@ module SwaggerYard
 end
 
 require "swagger_yard/rails/engine"
+require "swagger_yard/rails/route_inspector"

data/lib/swagger_yard/rails/engine.rb

@@ -4,12 +4,17 @@ module SwaggerYard
       isolate_namespace SwaggerYard::Rails
       initializer "swagger_yard-rails.finisher_hook" do |app|
         SwaggerYard.register_custom_yard_tags!
+        # Usage:
+        # @route my-named-route
+        ::YARD::Tags::Library.define_tag("Route", :route)
       end
 
       initializer "swagger_yard-rails.paths" do |app|
         SwaggerYard.configure do |config|
-          config.controller_path = ::Rails.root + 'app/controllers/**/*'
-          config.model_path      = ::Rails.root + 'app/models/**/*'
+          config.controller_path ||= ::Rails.root + 'app/controllers/**/*'
+          config.model_path      ||= ::Rails.root + 'app/models/**/*'
+
+          config.path_discovery_function = RouteInspector.discovery_function
         end
       end
 

data/lib/swagger_yard/rails/route_inspector.rb

@@ -0,0 +1,75 @@
+module SwaggerYard
+  module Rails
+    module RouteInspector
+      def self.discovery_function
+        JourneyRoutes.new(::Rails.application.routes.set)
+      end
+
+      class Error < ::RuntimeError
+      end
+
+      class JourneyRoutes
+        def initialize(routes)
+          @routes = routes
+        end
+
+        def call(yard_obj)
+          return nil if skip_object?(yard_obj)
+
+          info   = yard_info(yard_obj)
+          route  = find_route(info)
+          method = route.verb.source.gsub(/[$^]/, '')
+
+          raise Error, "no http method: #{info.inspect}" if method.empty?
+
+          path = route.parts.inject(route.ast.to_s) do |p,sym|
+            p.sub(sym.inspect, "{#{sym}}")
+          end
+
+          # FIXME: always remove format parameter?
+          path = path.sub('(.{format})', '')
+
+          [method, path]
+        end
+
+        alias_method :[], :call
+
+        private
+        def skip_object?(obj)
+          obj.scope != :instance ||
+            obj.visibility != :public ||
+            obj.docstring.blank?
+        end
+
+        def yard_info(obj)
+          {}.tap do |info|
+            route_tag = obj.tags.detect {|t| t.tag_name == 'route' }
+            if route_tag
+              info[:route] = route_tag.text
+            else
+              controller, action = obj.path.split obj.sep, 2
+              info[:action]      = action
+              info[:controller]  = controller.underscore.sub '_controller', ''
+            end
+          end
+        end
+
+        def find_route(info)
+          matching_routes = @routes.select do |r|
+            if info[:route]
+              r.name == info[:route]
+            else
+              r.defaults[:controller] == info[:controller] &&
+                r.defaults[:action] == info[:action]
+            end
+          end
+
+          raise Error, "too many matches: #{info.inspect}"  if matching_routes.size > 1
+          raise Error, "no matching route: #{info.inspect}" if matching_routes.size < 1
+
+          matching_routes.first
+        end
+      end
+    end
+  end
+end

data/lib/swagger_yard/rails/tasks.rake

@@ -1,7 +1,7 @@
 namespace :swagger do
   task :json, [:filename] => :environment do |t, args|
     File.open(args[:filename] || "swagger.json", "w") do |f|
-      f.puts JSON.pretty_generate(SwaggerYard::Swagger.new.swagger_v2)
+      f.puts JSON.pretty_generate(SwaggerYard::Swagger.new.to_h)
     end
   end
 end

data/lib/swagger_yard/rails/version.rb

@@ -1,5 +1,5 @@
 module SwaggerYard
   module Rails
-    VERSION = "0.2.0"
+    VERSION = "0.3.0"
   end
 end

data/swagger_yard-rails.gemspec

@@ -28,7 +28,7 @@ Gem::Specification.new do |spec|
   spec.require_paths = ["lib"]
 
   spec.add_dependency "rails", ">= 3.2.8"
-  spec.add_dependency "swagger_yard", "~> 0.2.0"
+  spec.add_dependency "swagger_yard", "~> 0.2"
 
   spec.add_development_dependency "bundler", "~> 1.10"
   spec.add_development_dependency "rake", "~> 10.0"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: swagger_yard-rails
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Tony Pitale
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2015-10-21 00:00:00.000000000 Z
+date: 2015-12-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -30,14 +30,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.2.0
+        version: '0.2'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.2.0
+        version: '0.2'
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
@@ -161,6 +161,7 @@ files:
 - config/routes.rb
 - lib/swagger_yard/rails.rb
 - lib/swagger_yard/rails/engine.rb
+- lib/swagger_yard/rails/route_inspector.rb
 - lib/swagger_yard/rails/tasks.rake
 - lib/swagger_yard/rails/version.rb
 - swagger_yard-rails.gemspec