richhollis / swagger-docs Goto Github PK

View Code? Open in Web Editor NEW

749.0 749.0 150.0 254 KB

Generates swagger-ui json files for Rails APIs with a simple DSL.

License: MIT License

Ruby 100.00%

swagger-docs's People

Contributors

Stargazers

Watchers

Forkers

jacke alvinlai tandibar rtsummit itrcdevs thatcosmonaut vanessanutrio thomascrenshaw jkappers synctree awesome rubysolo sanelson2000 ninech supairish cgutierrez radpad jonbell moxiespaces ayamomiji maheshgattani birchbox oki psorowka aaronrenner mje113 zakwanhaj mgraham alxpborges abratashov starfieldtms spilin andythurlow spacechurro wmv nthalk svanhess unboxed tiagoamaro voidet denwwer notonthehighstreet klittlepage mjbamford frograms tbtalbottjr hornc donaldpiret krakatoa hderms charanya15 sivsushruth dr-impossible iloan misterrager benmort parmandil pedantix kamoh ltvco annotis dogwood008 muthhus pranavpr arvinzr publicstuff arturmalecki bioritmo flux-app billy3321 imlitech kizinatural jiffinc sb8244 chetan-clickapps frodrigo roxer arround dcarneiro gbaychev iirving acpk jdlombardozzi steventen rschumann fenhy catawiki heberuriegas rbakhshi breakoutbit rudskikhivan ado anhtrantuan pinak1180 sonots adrientoub code-farmer-ming kwerle flemon dtusk

swagger-docs's Issues

should precompilation automatically kick off the functionality of your rake task?

Feature request:

In order to keep documentation in sync
As a system admin
I want to generate json file on each precompilation

I suggest you could change the readme to show how you can put this in the 'assets' bundler group, and a tweak to insert in the assets pipeline

Custom headers?

I need all swagger api actions to set a custom header to my server. How do I do this?

1.0: 3 processed / 2 skipped

After I run "rake swagger:docs" for the swagger docs sample, it showed : "1.0: 3 processed / 2 skipped".
What does it mean?

Question: How do I document my controllers? should my controller inherit ApiController?

Hi, having a hard time trying to generate a useful json file for swagger. Should my controller inherit ApiController? The rake task is not fetching any documentation..

Thanks.

undefined method `source' for "GET":String

I'm getting this stack trace when trying to generate doc. You can see the ancient versions of Rails, Rake, and even Ruby that I'm running. Let me know what other information would be helpful for debugging.

undefined method `source' for "GET":String
/Users/kinman/.rvm/gems/ruby-1.9.3-p484@master/gems/swagger-docs-0.1.8/lib/swagger/docs/generator.rb:147:in `get_route_path_apis'
/Users/kinman/.rvm/gems/ruby-1.9.3-p484@master/gems/swagger-docs-0.1.8/lib/swagger/docs/generator.rb:128:in `block in process_path'
/Users/kinman/.rvm/gems/ruby-1.9.3-p484@master/gems/swagger-docs-0.1.8/lib/swagger/docs/generator.rb:127:in `each'
/Users/kinman/.rvm/gems/ruby-1.9.3-p484@master/gems/swagger-docs-0.1.8/lib/swagger/docs/generator.rb:127:in `process_path'
/Users/kinman/.rvm/gems/ruby-1.9.3-p484@master/gems/swagger-docs-0.1.8/lib/swagger/docs/generator.rb:62:in `block in generate_doc'
/Users/kinman/.rvm/gems/ruby-1.9.3-p484@master/gems/swagger-docs-0.1.8/lib/swagger/docs/generator.rb:61:in `each'
/Users/kinman/.rvm/gems/ruby-1.9.3-p484@master/gems/swagger-docs-0.1.8/lib/swagger/docs/generator.rb:61:in `generate_doc'
/Users/kinman/.rvm/gems/ruby-1.9.3-p484@master/gems/swagger-docs-0.1.8/lib/swagger/docs/generator.rb:49:in `block in generate_docs'
/Users/kinman/.rvm/gems/ruby-1.9.3-p484@master/gems/swagger-docs-0.1.8/lib/swagger/docs/generator.rb:46:in `each'
/Users/kinman/.rvm/gems/ruby-1.9.3-p484@master/gems/swagger-docs-0.1.8/lib/swagger/docs/generator.rb:46:in `generate_docs'
/Users/kinman/.rvm/gems/ruby-1.9.3-p484@master/gems/swagger-docs-0.1.8/lib/swagger/docs/generator.rb:20:in `write_docs'
/Users/kinman/.rvm/gems/ruby-1.9.3-p484@master/gems/swagger-docs-0.1.8/lib/tasks/swagger.rake:5:in `block (2 levels) in <top (required)>'
/Users/kinman/.rvm/gems/ruby-1.9.3-p484@master/gems/rake-0.8.7/lib/rake.rb:636:in `call'
/Users/kinman/.rvm/gems/ruby-1.9.3-p484@master/gems/rake-0.8.7/lib/rake.rb:636:in `block in execute'
/Users/kinman/.rvm/gems/ruby-1.9.3-p484@master/gems/rake-0.8.7/lib/rake.rb:631:in `each'
/Users/kinman/.rvm/gems/ruby-1.9.3-p484@master/gems/rake-0.8.7/lib/rake.rb:631:in `execute'
/Users/kinman/.rvm/gems/ruby-1.9.3-p484@master/gems/rake-0.8.7/lib/rake.rb:597:in `block in invoke_with_call_chain'
/Users/kinman/.rvm/rubies/ruby-1.9.3-p484/lib/ruby/1.9.1/monitor.rb:211:in `mon_synchronize'
/Users/kinman/.rvm/gems/ruby-1.9.3-p484@master/gems/rake-0.8.7/lib/rake.rb:590:in `invoke_with_call_chain'
/Users/kinman/.rvm/gems/ruby-1.9.3-p484@master/gems/rake-0.8.7/lib/rake.rb:583:in `invoke'
/Users/kinman/.rvm/gems/ruby-1.9.3-p484@master/gems/rake-0.8.7/lib/rake.rb:2051:in `invoke_task'
/Users/kinman/.rvm/gems/ruby-1.9.3-p484@master/gems/rake-0.8.7/lib/rake.rb:2029:in `block (2 levels) in top_level'
/Users/kinman/.rvm/gems/ruby-1.9.3-p484@master/gems/rake-0.8.7/lib/rake.rb:2029:in `each'
/Users/kinman/.rvm/gems/ruby-1.9.3-p484@master/gems/rake-0.8.7/lib/rake.rb:2029:in `block in top_level'
/Users/kinman/.rvm/gems/ruby-1.9.3-p484@master/gems/airbrake-3.1.8/lib/airbrake/rake_handler.rb:39:in `standard_exception_handling'
/Users/kinman/.rvm/gems/ruby-1.9.3-p484@master/gems/rake-0.8.7/lib/rake.rb:2023:in `top_level'
/Users/kinman/.rvm/gems/ruby-1.9.3-p484@master/gems/rake-0.8.7/lib/rake.rb:2001:in `block in run'
/Users/kinman/.rvm/gems/ruby-1.9.3-p484@master/gems/rake-0.8.7/lib/rake.rb:2068:in `standard_exception_handling'
/Users/kinman/.rvm/gems/ruby-1.9.3-p484@master/gems/rake-0.8.7/lib/rake.rb:1998:in `run'
/Users/kinman/.rvm/gems/ruby-1.9.3-p484@master/gems/rake-0.8.7/bin/rake:31:in `<top (required)>'
/Users/kinman/.rvm/gems/ruby-1.9.3-p484@master/bin/rake:23:in `load'
/Users/kinman/.rvm/gems/ruby-1.9.3-p484@master/bin/rake:23:in `<main>'

"Error": "You need to sign in or sign up before continuing."

I'm using the devise gem, and I place "before_filter :authenticate_user!" in my controller. Whenever I'm using the Swagger-UI, it's telling me I need to sign in with the error "you need to sign in or sign up before continuing."

Recurring param without duplication (for instance "Authentication" header)

Hello,

Tons of methods of my API require authentication (via a header) so I wonder if there is a way to avoid duplicating the param call in every swagger_api block:

param :header, 'Authentication-Token', :string, :required, 'Authentication token'

Thanks!

feature idea: add magic. use tests to determine possible error responses

It should be possible to eliminate boilerplate by integrating with some common test libraries. I would start with rails-minitest controller tests.

In the long run, I think DSL might be restricted to customizing descriptions.

In the intermediate / short run, I would just make a rails-specific test plugin that lists all the tested error states during controller tests, and prints them out after minitest finishes.

Thoughts on the long-term goal?

Does it work with rails-api?

Hi, I have my current project build with rails-api(https://github.com/rails-api/rails-api) but not rails. But somehow the rake swagger:docs task always shows "processed 0" to me. I tried the example with rails-api and it didn't seem work either. I wonder does it have something to do with it? Thanks!

Does it work with rails-api?

swagger definition without params throws errors

Let's say I have an API call which takes no parameters, perhaps something like /me to get my own information.

Swagger Definition

  swagger_api :index do
    summary 'Gets the current users likes.'
  end

Currently, this will cause error on line 143 undefined method `reject' for nil:NilClass.

142         def filter_path_params(path, params)
143           params.reject do |param|
144             param_as_variable = "{#{param[:name]}}"
145             param[:param_type] == :path && !path.include?(param_as_variable)
146           end
147         end

So, it looks like params should be an empty list before it gets in here, or reworked to check for nil.

Reloading development server causes undefined method `swagger_controller'

Trying out swagger-docs adn it's pretty sweet.

However -- on a development server where I'm allowing automatic reload -- I end up with undefined methodswagger_controller'` unless I restart the development server.

Am I configuring something wrong for this to happen?

Nested Resources in Rails

Hi,
I'm trying to figure out how to implement swagger in my rails app. I have it working for top level resources, but for nested resources I can't find a solution.

Let's say I have:

resources :products do
    resources :slots
end

How do I structure the

swagger_controller :slots, "Slot Management"

for building my slots methods based on my slots controller actions?

The documentation just refers to a simple top level resource (users).

Appreciate any advice you can give

thanks

Steve

Required properties are camelized inconsistently

Required properties on a model aren't camelized when camelize_model_properties is set to true (the default).

As an example, the following was generated when camelization was enabled:

"Account": {
"id": "Account",
"required": [
"account_name",
],
"properties": {
"accountName": {
"type": "string",
"description": "Blah"
}
},
"description": "Foo"
}
Note that "accountName" isn't camelized in the list of required fields. Disabling camelization gives the expected behavior.

"Account": {
"id": "Account",
"required": [
"account_name"
],
"properties": {
"account_name": {
"type": "string",
"description": "Blah"
}
},
"description": "Foo"
}

Please make 'transform_path' part of the configuration

We have a 'swagger_docs' discovery url - that we are using transform_path for it works.

We have a 'base_path' for the API that is the actual live api.

The trouble with the config as is - our swagger 'discovery_path' gets conflated with the 'base_path' and then we end up with swagger_ui generating weird paths.

Transform_path solved our issue - perhaps the config could have a seperate config key for 'swagger_base_path' for the server location of the swagger docs to replace monkeypatching transform_path.

Thank you for your consideration.

Can I group methods of different controllers?

Hi!

I'm find Swagger very useful and great product. But I can't find a sloution of my task. May be any help me?

I'm make a project, and for more easy maintance make 2-3 actions in one controller. For example, I have module now, which include 8 controllers and 18 actions. When I generate a API with swagger, I see many controllers. :(

Does swagger have a possibility group a different actions from any controllers?

Best,
Stan

Can't run tests

I'm having trouble running the tests on this gem (I'm trying to submit a patch). Here's what I've encountered so far:

% bundle install
Fetching gem metadata from https://rubygems.org/..........
Fetching additional metadata from https://rubygems.org/..
Resolving dependencies...
Could not find gem 'active_support (~> 3) ruby' in the gems available on this machine.

This is apparently an issue with the active_support gem name changing (??). I can get pat it by removing the underscore:

% sed -i '' -e 's/active_support/activesupport/' swagger-docs.gemspec
% bundle install
Resolving dependencies...
Using rake 10.3.2
Using i18n 0.6.11
Using multi_json 1.10.1
Using activesupport 3.2.19
Using bundler 1.6.2
Using thor 0.19.1
Using appraisal 1.0.0
Using diff-lcs 1.2.5
Using rspec-support 3.0.2
Using rspec-core 3.0.2
Using rspec-expectations 3.0.2
Using rspec-mocks 3.0.2
Using rspec 3.0.0
Using swagger-docs 0.1.8 from source at .
Your bundle is complete!
Use `bundle show [gemname]` to see where a bundled gem is installed.

So far so good, but then if I try to run the tests...

% bundle exec rake
/Users/tlittle/.rvm/rubies/ruby-2.1.1/bin/ruby -I/Users/tlittle/.rvm/gems/ruby-2.1.1@swagger/gems/rspec-core-3.0.2/lib:/Users/tlittle/.rvm/gems/ruby-2.1.1@swagger/gems/rspec-support-3.0.2/lib -S /Users/tlittle/.rvm/gems/ruby-2.1.1@swagger/gems/rspec-core-3.0.2/exe/rspec ./spec/lib/swagger/docs/api_declaration_file_metadata_spec.rb ./spec/lib/swagger/docs/api_declaration_file_spec.rb ./spec/lib/swagger/docs/config_spec.rb ./spec/lib/swagger/docs/generator_spec.rb
/Users/tlittle/code/swagger-docs/spec/spec_helper.rb:1:in `require': cannot load such file -- rails (LoadError)
        from /Users/tlittle/code/swagger-docs/spec/spec_helper.rb:1:in `<top (required)>'
        from /Users/tlittle/code/swagger-docs/spec/lib/swagger/docs/api_declaration_file_metadata_spec.rb:1:in `require'
        from /Users/tlittle/code/swagger-docs/spec/lib/swagger/docs/api_declaration_file_metadata_spec.rb:1:in `<top (required)>'
        from /Users/tlittle/.rvm/gems/ruby-2.1.1@swagger/gems/rspec-core-3.0.2/lib/rspec/core/configuration.rb:1057:in `load'
        from /Users/tlittle/.rvm/gems/ruby-2.1.1@swagger/gems/rspec-core-3.0.2/lib/rspec/core/configuration.rb:1057:in `block in load_spec_files'
        from /Users/tlittle/.rvm/gems/ruby-2.1.1@swagger/gems/rspec-core-3.0.2/lib/rspec/core/configuration.rb:1057:in `each'
        from /Users/tlittle/.rvm/gems/ruby-2.1.1@swagger/gems/rspec-core-3.0.2/lib/rspec/core/configuration.rb:1057:in `load_spec_files'
        from /Users/tlittle/.rvm/gems/ruby-2.1.1@swagger/gems/rspec-core-3.0.2/lib/rspec/core/runner.rb:97:in `setup'
        from /Users/tlittle/.rvm/gems/ruby-2.1.1@swagger/gems/rspec-core-3.0.2/lib/rspec/core/runner.rb:85:in `run'
        from /Users/tlittle/.rvm/gems/ruby-2.1.1@swagger/gems/rspec-core-3.0.2/lib/rspec/core/runner.rb:70:in `run'
        from /Users/tlittle/.rvm/gems/ruby-2.1.1@swagger/gems/rspec-core-3.0.2/lib/rspec/core/runner.rb:38:in `invoke'
        from /Users/tlittle/.rvm/gems/ruby-2.1.1@swagger/gems/rspec-core-3.0.2/exe/rspec:4:in `<main>'
/Users/tlittle/.rvm/rubies/ruby-2.1.1/bin/ruby -I/Users/tlittle/.rvm/gems/ruby-2.1.1@swagger/gems/rspec-core-3.0.2/lib:/Users/tlittle/.rvm/gems/ruby-2.1.1@swagger/gems/rspec-support-3.0.2/lib -S /Users/tlittle/.rvm/gems/ruby-2.1.1@swagger/gems/rspec-core-3.0.2/exe/rspec ./spec/lib/swagger/docs/api_declaration_file_metadata_spec.rb ./spec/lib/swagger/docs/api_declaration_file_spec.rb ./spec/lib/swagger/docs/config_spec.rb ./spec/lib/swagger/docs/generator_spec.rb failed

Seems like there's a dependency on rails, not just activesupport, so i try to switch to that:

% sed -i '' -e 's/activesupport/rails/' swagger-docs.gemspec
% bundle install
Resolving dependencies...
--SNIP--
Your bundle is complete!
Use `bundle show [gemname]` to see where a bundled gem is installed.

But then when I try to run the tests I get a bunch of failures.

% bundle exec rake
/Users/tlittle/.rvm/rubies/ruby-2.1.1/bin/ruby -I/Users/tlittle/.rvm/gems/ruby-2.1.1@swagger/gems/rspec-core-3.0.2/lib:/Users/t
little/.rvm/gems/ruby-2.1.1@swagger/gems/rspec-support-3.0.2/lib -S /Users/tlittle/.rvm/gems/ruby-2.1.1@swagger/gems/rspec-core
-3.0.2/exe/rspec ./spec/lib/swagger/docs/api_declaration_file_metadata_spec.rb ./spec/lib/swagger/docs/api_declaration_file_spe
c.rb ./spec/lib/swagger/docs/config_spec.rb ./spec/lib/swagger/docs/generator_spec.rb
.....................FFFFFFF..FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF

Failures:

  1) Swagger::Docs::Generator without controller base path resources files writes basePath correctly
     Failure/Error: generate(config)
     NoMethodError:
       undefined method `deep_merge!' for {}:Hash
     # ./lib/swagger/docs/methods.rb:19:in `block in swagger_actions'
     # ./lib/swagger/docs/methods.rb:16:in `each'
     # ./lib/swagger/docs/methods.rb:16:in `swagger_actions'
     # ./lib/swagger/docs/generator.rb:148:in `get_route_path_apis'
     # ./lib/swagger/docs/generator.rb:128:in `block in process_path'
     # ./lib/swagger/docs/generator.rb:61:in `generate_doc'
     # ./lib/swagger/docs/generator.rb:49:in `block in generate_docs'
     # ./lib/swagger/docs/generator.rb:46:in `each'
     # ./lib/swagger/docs/generator.rb:46:in `generate_docs'
     # ./lib/swagger/docs/generator.rb:20:in `write_docs'
     # ./spec/spec_helper.rb:21:in `generate'
     # ./spec/lib/swagger/docs/generator_spec.rb:40:in `block (3 levels) in <top (required)>'

# a bunch more of the same...

What am I missing here?

File attachments

Hi Richard,

First of all thank you so much for putting this gem together. Quick question, I believe the swagger spec supports file uploads. Does this gem support it? I have tried a few different things and have not been so successful at getting it to work.

Kind Regards
Shirren

:controller_base_path option required

Hi rich,

I have one of the problems Manuel mentioned Issue #1 ... He failed to open a separate issue.

I can confirm that on 3.2.16 I have seen that leaving ":controller_base_path" off is causing error ... only on rake task. (see below) I, like manuel, have subclassed folders in my controller directory.

adding ":controller_base_path => "api/",' fixes the problem.

I think the problem has something to do with the scope of execution. Perhaps try ::Library::DocumentsController instead of Library::DocumentsController ?

rake swagger:docs --trace
** Invoke swagger:docs (first_time)
** Invoke environment (first_time)
** Execute environment
** Execute swagger:docs
rake aborted!
uninitialized constant Library::DocumentsController
/opt/boxen/rbenv/versions/2.0.0-p247/lib/ruby/gems/2.0.0/gems/activesupport-3.2.16/lib/active_support/inflector/methods.rb:230:in block in constantize' /opt/boxen/rbenv/versions/2.0.0-p247/lib/ruby/gems/2.0.0/gems/activesupport-3.2.16/lib/active_support/inflector/methods.rb:229:ineach'
/opt/boxen/rbenv/versions/2.0.0-p247/lib/ruby/gems/2.0.0/gems/activesupport-3.2.16/lib/active_support/inflector/methods.rb:229:in constantize' /opt/boxen/rbenv/versions/2.0.0-p247/lib/ruby/gems/2.0.0/gems/activesupport-3.2.16/lib/active_support/core_ext/string/inflections.rb:54:inconstantize'
/opt/boxen/rbenv/versions/2.0.0-p247/lib/ruby/gems/2.0.0/gems/swagger-docs-0.0.3/lib/swagger/docs/generator.rb:88:in `block in write_doc'

Patch vs Put

Rails now uses Patch instead of Put, but the swagger-docs gem creates both in the description. Is this on purpose? Or is this a bug?

Question: More than one api-docs.json?

I have a rather unusual question: we have an app with several separated APIs for different
type of consumers of the API. We want to separate the documentation, too.

Is this possible with swagger-docs?

Param as an array of swagger_model object?

Hi, in a Ruby on Rails application, we have a swagger_model called Disk and the following is the parameter I am specifying in the corresponding swagger_api entry:

param :body, :disks, :Disk, :optional, "An array of disks"

How could I make this parameter an array in order to behave like this example: http://petstore.swagger.wordnik.com/#!/user/createUsersWithArrayInput ?

Thanks in advance

Response Class

how to define response class?
Like this
http://petstore.swagger.wordnik.com/#!/pet/getPetById

Feature-idea: support fine-grained authorizations

One strong use-case for a machine-readable format such as swagger is for applications that have authorizations: documentation lookup, documentation exploration as well as RPC client experiences are greatly enhanced by delivering only the relevant subset of features to end users.

How to do this? I'm really not sure. Some applications have complicated authorization schemes. Perhaps spike by making adapter for cancan so that authorizations are specified by swagger-docs dsl?

I do not currently have such a need, but I wanted to note this as a possible feature.

Routing Issue

I wanted to generate an POST endpoint "/services/:id/report", where a reports gets generated for a particular service identified by the "id". In the backend, it would make more sense for the report to be created in my ReportsController. Somehow when I added "to: 'reports#create'" to my route, the endpoint "/services/:id/report" is NOT generated. Any ideas?

routes.rb

resources :services do
post 'report', on: :member, to: 'reports#create'
end

401 exception when hitting the swagger in browser

Hi,

I am hitting the swagger from Browser

http://localhost:8080/rest/api-docs

But I am gettinh 401 exception..

Please guide me.

I followed the below tutorial

https://github.com/wordnik/swagger-core/wiki/Java-JAXRS-Quickstart

Support for Rails Engines

We use Rails Engines to segment some components of our app—for example, we have an "api" engine which is mounted in the main app. I've been trying to get swagger-docs to work for that, but Engines seem to make route/controller discovery more complicated so I am unable to generate docs either from the main app or from the engine itself.

These are the relevant lines in generator.rb:

paths = Rails.application.routes.routes.map{|i| "#{i.defaults[:controller]}" }
[...]
Rails.application.routes.routes.select{|i| i.defaults[:controller] == path}.each do |route|

...which, when running swagger from the main app, this results in 1.0: 0 processed / 0 skipped since the api controllers aren't discovered.

You can get at the engine routes from <Route>.app.app.routes.routes, but that seems complicated and may include engines from other random gem dependencies.

I'm happy to look at making a pull request for this if you'd like, but what do you think is the best strategy here? Maybe you can just pull out the route discovery code to its own method so that it could be more easily overridden for this use case?

Complex parameters

I have been playing around with swagger-docs and I have run into an issue that may or may not be possible.

Is it possible to create parameters like below?

{
  "user" : 
    {
      "email" : "[email protected]",
      "passowrd" : "password1234"
    }
}

param type "path" works only for DELETE endpoints

As in the title. When I add "path" patameter to :show action it doesn't appear in the generated JSON file. It works only for :destroy

Output folder structure incorrect for namespaced controllers

With namespaced controllers the correct path is generated in the .json output files but all of them are written at the base path and not under a folder named after their own namespace.

e.g. Api::EmployeesController should be output to base_path/api/employees.json, instead it goes to base_path/employees.json

Error when running rake swagger:docs

I'm getting this error when using v1.3

rake aborted!
TypeError: no implicit conversion of Symbol into Integer
/home/avitus/.bundler/ruby/2.0.0/swagger-docs-8ded501fc4a5/lib/swagger/docs/generator.rb:112:in `[]'
/home/avitus/.bundler/ruby/2.0.0/swagger-docs-8ded501fc4a5/lib/swagger/docs/generator.rb:112:in `block in process_path'
/home/avitus/.bundler/ruby/2.0.0/swagger-docs-8ded501fc4a5/lib/swagger/docs/generator.rb:110:in `each'
/home/avitus/.bundler/ruby/2.0.0/swagger-docs-8ded501fc4a5/lib/swagger/docs/generator.rb:110:in `process_path'
/home/avitus/.bundler/ruby/2.0.0/swagger-docs-8ded501fc4a5/lib/swagger/docs/generator.rb:44:in `block in write_doc'
/home/avitus/.bundler/ruby/2.0.0/swagger-docs-8ded501fc4a5/lib/swagger/docs/generator.rb:43:in `each'
/home/avitus/.bundler/ruby/2.0.0/swagger-docs-8ded501fc4a5/lib/swagger/docs/generator.rb:43:in `write_doc'
/home/avitus/.bundler/ruby/2.0.0/swagger-docs-8ded501fc4a5/lib/swagger/docs/generator.rb:26:in `block in write_docs'
/home/avitus/.bundler/ruby/2.0.0/swagger-docs-8ded501fc4a5/lib/swagger/docs/generator.rb:24:in `each'
/home/avitus/.bundler/ruby/2.0.0/swagger-docs-8ded501fc4a5/lib/swagger/docs/generator.rb:24:in `write_docs'
/home/avitus/.bundler/ruby/2.0.0/swagger-docs-8ded501fc4a5/lib/tasks/swagger.rake:5:in `block (2 levels) in <top (required)>'

Issues with DoorKeeper Gem and my API

I have a custom BaseController for my API, something along these lines:

class Api::V1::BaseController < ActionController::Base
  before_action   :set_user
  doorkeeper_for  :all

private

  def set_user
    @user = User.find(doorkeeper_token.resource_owner_id) if doorkeeper_token
  end
end

I was trying to implement the first of my API Controllers, but i get this error when I run rake swagger:docs :

NoMethodError: undefined method `doorkeeper_for' for Api::V1::BaseController:Class
/Users/jAv/dev/*******/app/controllers/api/v1/base_controller.rb:3:in `<class:BaseController>'
/Users/jAv/dev/*******/app/controllers/api/v1/base_controller.rb:1:in `<top (required)>'
/Users/jAv/.rvm/gems/ruby-2.1.1@global/gems/activesupport-4.1.1/lib/active_support/dependencies.rb:443:in `load'
/Users/jAv/.rvm/gems/ruby-2.1.1@global/gems/activesupport-4.1.1/lib/active_support/dependencies.rb:443:in `block in load_file'
/Users/jAv/.rvm/gems/ruby-2.1.1@global/gems/activesupport-4.1.1/lib/active_support/dependencies.rb:633:in `new_constants_in'
/Users/jAv/.rvm/gems/ruby-2.1.1@global/gems/activesupport-4.1.1/lib/active_support/dependencies.rb:442:in `load_file'
/Users/jAv/.rvm/gems/ruby-2.1.1@global/gems/activesupport-4.1.1/lib/active_support/dependencies.rb:342:in `require_or_load'
/Users/jAv/.rvm/gems/ruby-2.1.1@global/gems/activesupport-4.1.1/lib/active_support/dependencies.rb:480:in `load_missing_constant'
/Users/jAv/.rvm/gems/ruby-2.1.1@global/gems/activesupport-4.1.1/lib/active_support/dependencies.rb:180:in `const_missing'
/Users/jAv/dev/*******/config/initializers/swagger_docs.rb:2:in `base_api_controller'
/Users/jAv/.rvm/gems/ruby-2.1.1/gems/swagger-docs-0.1.8/lib/swagger/docs/config.rb:20:in `register_apis'
/Users/jAv/******/config/initializers/swagger_docs.rb:5:in `<top (required)>'
/Users/jAv/.rvm/gems/ruby-2.1.1@global/gems/activesupport-4.1.1/lib/active_support/dependencies.rb:241:in `load'
/Users/jAv/.rvm/gems/ruby-2.1.1@global/gems/activesupport-4.1.1/lib/active_support/dependencies.rb:241:in `block in load'
/Users/jAv/.rvm/gems/ruby-2.1.1@global/gems/activesupport-4.1.1/lib/active_support/dependencies.rb:232:in `load_dependency'
/Users/jAv/.rvm/gems/ruby-2.1.1@global/gems/activesupport-4.1.1/lib/active_support/dependencies.rb:241:in `load'
/Users/jAv/.rvm/gems/ruby-2.1.1@global/gems/railties-4.1.1/lib/rails/engine.rb:648:in `block in load_config_initializer'
/Users/jAv/.rvm/gems/ruby-2.1.1@global/gems/activesupport-4.1.1/lib/active_support/notifications.rb:161:in `instrument'
/Users/jAv/.rvm/gems/ruby-2.1.1@global/gems/railties-4.1.1/lib/rails/engine.rb:647:in `load_config_initializer'
/Users/jAv/.rvm/gems/ruby-2.1.1@global/gems/railties-4.1.1/lib/rails/engine.rb:612:in `block (2 levels) in <class:Engine>'
/Users/jAv/.rvm/gems/ruby-2.1.1@global/gems/railties-4.1.1/lib/rails/engine.rb:611:in `each'
/Users/jAv/.rvm/gems/ruby-2.1.1@global/gems/railties-4.1.1/lib/rails/engine.rb:611:in `block in <class:Engine>'
/Users/jAv/.rvm/gems/ruby-2.1.1@global/gems/railties-4.1.1/lib/rails/initializable.rb:30:in `instance_exec'
/Users/jAv/.rvm/gems/ruby-2.1.1@global/gems/railties-4.1.1/lib/rails/initializable.rb:30:in `run'
/Users/jAv/.rvm/gems/ruby-2.1.1@global/gems/railties-4.1.1/lib/rails/initializable.rb:55:in `block in run_initializers'
/Users/jAv/.rvm/gems/ruby-2.1.1@global/gems/railties-4.1.1/lib/rails/initializable.rb:44:in `each'
/Users/jAv/.rvm/gems/ruby-2.1.1@global/gems/railties-4.1.1/lib/rails/initializable.rb:44:in `tsort_each_child'
/Users/jAv/.rvm/gems/ruby-2.1.1@global/gems/railties-4.1.1/lib/rails/initializable.rb:54:in `run_initializers'
/Users/jAv/.rvm/gems/ruby-2.1.1@global/gems/railties-4.1.1/lib/rails/application.rb:288:in `initialize!'
/Users/jAv/.rvm/gems/ruby-2.1.1@global/gems/railties-4.1.1/lib/rails/railtie.rb:194:in `public_send'
/Users/jAv/.rvm/gems/ruby-2.1.1@global/gems/railties-4.1.1/lib/rails/railtie.rb:194:in `method_missing'
/Users/jAv/dev/*****/config/environment.rb:5:in `<top (required)>'
/Users/jAv/.rvm/gems/ruby-2.1.1@global/gems/activesupport-4.1.1/lib/active_support/dependencies.rb:247:in `require'
/Users/jAv/.rvm/gems/ruby-2.1.1@global/gems/activesupport-4.1.1/lib/active_support/dependencies.rb:247:in `block in require'
/Users/jAv/.rvm/gems/ruby-2.1.1@global/gems/activesupport-4.1.1/lib/active_support/dependencies.rb:232:in `load_dependency'
/Users/jAv/.rvm/gems/ruby-2.1.1@global/gems/activesupport-4.1.1/lib/active_support/dependencies.rb:247:in `require'
/Users/jAv/.rvm/gems/ruby-2.1.1@global/gems/railties-4.1.1/lib/rails/application.rb:264:in `require_environment!'
/Users/jAv/.rvm/gems/ruby-2.1.1@global/gems/railties-4.1.1/lib/rails/application.rb:367:in `block in run_tasks_blocks'
/Users/jAv/.rvm/gems/ruby-2.1.1/bin/ruby_executable_hooks:15:in `eval'
/Users/jAv/.rvm/gems/ruby-2.1.1/bin/ruby_executable_hooks:15:in `<main>'
Tasks: TOP => swagger:docs => environment

I could use a hand, thank you!

Hack: Add functionality for high-level tutorials

The main reason teams that I have worked with have NOT used swagger/wadl in the past is the need for more comprehensive tutorials. (e.g. https://docs.clause-logic.com/v2)

Although it is out of scope for the swagger specification, it may be in scope for a rails gem to have complementary jekyll-like generation of pages from existing templates, into public directory.

Thoughts?

Can't generate a working configuration for two API versions

I've been fighting for hours trying to get a working config file for swagger-docs, without success. Could use some help.
Here is how things are set up for me (using a Rails app):
controllers:

controllers ->
  api ->
    v1 ->
      api_controller.rb
      orders_controller.rb
    v2 ->
      api_controller.rb
      orders_controller.rb

Here is the relevant part of my routes:

constraints(ApiMatcher) do
    namespace :api, path: '/' do
      namespace :v2, path: 'v2', as: 'v2' do
        resources :orders, only: [:index, :create, :show, :update, :destroy]
      end

      namespace :v1, path: 'v1', as: 'v1' do
        get '/orders/list', to: 'io#index'

      end
    end
  end

Now I'm finding it completely impossible to get swagger-docs to generate the proper path for both the docs and the actual resources

Here's what I'm trying:

Swagger::Docs::Config.register_apis({
  'v1' => {
    # the extension used for the API
    api_extension_type: :json,
    # the output location where your .json files are written to
    api_file_path: 'public/api/v1',
    # the URL base path to your API
    base_path: 'http://api.poblano.dev:3000',
    controller_base_path: 'api/v1',
    # if you want to delete all .json files at each generation
    clean_directory: true,
    camelize_model_properties: false
  },
  'v2' => {
    # the extension used for the API
    api_extension_type: :json,
    # the output location where your .json files are written to
    api_file_path: 'public/api/v2',
    api_file_name: 'v2.json',
    # the URL base path to your API
    base_path: 'http://api.poblano.dev:3000',
    controller_base_path: 'api/v2',
    # if you want to delete all .json files at each generation
    clean_directory: true,
    camelize_model_properties: false
  }
})

If I don't add the controller_base_path property then the generated paths are correct, but documentation for every single endpoint is generated for both api versions (so it doesn't scope by the proper controller namespace). If I do add the controller_base_path property however my resource paths in the generated documentation look like this:

  "basePath": "http://api.poblano.dev:3000/api/v2/",
  "resourcePath": "carriers",
  "apis": [
    {
      "path": "v2/carriers.json",

Resulting in duplication. I want to get rid of the api/v2 in the base path of the resources. Please help!

Support for paramType: body?

The petstore example for create shows specifying a JSON body as the content submitted to the endpoint. Is there a way to specify that in swagger:docs?

Request to tag a new release

This project is great! Could do you do a new gem release to incorporate the changes from the last few months? Right now I'm having to pull from the git repo directly, but would like to drop that.

Support for adding the info element

Similar to the info the top of this page.
http://petstore.swagger.wordnik.com/

Does it support response class?

I wonder if there is a way I can do something similar to the Java counterpart.
response = Person.class

Thanks!

behaviour of common documentation

I tried to set up my common parameters as described in https://github.com/richhollis/swagger-docs#drying-up-common-documentation but seems that not work as expected:

# base class
def setup_basic_api_documentation
  swagger_api :index do
    param :query, :page, :string, :optional, 'Page number'
  end
end

# controller
swagger_api :index do                                                                                                                                                                                                                                                 
summary "My method summary"                                                                                                                                                                                                                                                                  
  param :query, :filter, :string, :required, "Filter column"                                                                                                                                                                                                              
  response :unauthorized                                                                                                                                                                                                   
end

The expected behaviour should be a documentation endpoint with page and filter params, isn't it?

What I get is a documentation enpoint only with page parameter.

Implementation Notes

I've noticed that there's not a way to add "Implementation notes" to individual API endpoints currently. I manually added

def notes(notes)
    @notes = notes
end

to dsl.rb, and these notes can be automatically generated then by adding a "notes" line to each swagger_api.
I haven't forked the project yet or submitted a pull request, but I just thought I'd throw that out there to see if anyone else is interested in this sort of functionality.

Question: Is there support for $ref

Is there a way to define references?

https://github.com/wordnik/swagger-spec/blob/master/versions/1.2.md#433-data-type-fields

Missing description for parameters defined by param_list

This snippet of code:

swagger_api :update do
  summary "Updates an existing Camera"
  param :form, 'camera[shape]', :string, :optional, "Shape"
  param_list :form, 'camera[shape]', :string, :optional, "Shape", ['box', 'bullet', 'dome']
end

Generates this:

{
  "paramType": "query",
  "name": "q[shape_eq]",
  "type": "string",
  "description": null,
  "required": false,
  "allowableValues": {
    "valueType": "LIST",
    "values": [
      "dome",
      "bullet",
      "box"
    ]
  }
}

Is this a bug or I am missing something?

Support for response Objects?

Hi! Any thoughts for generation of response object in an api endpoint?

edit: also called, the response class

Can't load docs

I have generated api, but it doesn't create index.html to view it.

underscored property names become automatically camel-cased in models

For example:

  swagger_model :mail_group_member do
    description "A mail group member object"
    property :id, :integer, :required, "Mail account ID"
    property :mail_group_id, :integer, :required, "Mail Group ID"
    property :address, :string, :required, "Email address"
  end

Winds up generating JSON that looks like:

"models": {
    "mailGroupMember": {
      "id": "mail_group_member",
      "required": [
        "id",
        "mail_group_id",
        "address"
      ],
      "properties": {
        "id": {
          "type": "integer",
          "description": "Mail account ID"
        },
        "mailGroupId": {
          "type": "integer",
          "description": "Mail Group ID"
        },
        "address": {
          "type": "string",
          "description": "Email address"
        }
    }
}

Is there a way around this?

Do not require params

Do not require param in DSL.

        swagger_controller :settings, 'User Settings Management'

        swagger_api :show do
            summary 'Gets user settings data'
            #param :query, :page, :integer, :optional, 'Page number'
            response :unauthorized
            response :not_found
        end

Adding the above pagination param is the only way to get swagger-docs to generate json. Without the param :query line, rake swagger:docs fails:

rake swagger:docs --trace

** Invoke swagger:docs (first_time)
** Invoke environment (first_time)
** Execute environment
** Execute swagger:docs
rake aborted!
undefined method `reject' for nil:NilClass
/Users/cdcooksey/.rvm/gems/ruby-2.0.0-p195/gems/swagger-docs-0.1.1/lib/swagger/docs/generator.rb:143:in `filter_path_params'
/Users/cdcooksey/.rvm/gems/ruby-2.0.0-p195/gems/swagger-docs-0.1.1/lib/swagger/docs/generator.rb:113:in `block (2 levels) in write_doc'
/Users/cdcooksey/.rvm/gems/ruby-2.0.0-p195/gems/swagger-docs-0.1.1/lib/swagger/docs/generator.rb:105:in `each'
/Users/cdcooksey/.rvm/gems/ruby-2.0.0-p195/gems/swagger-docs-0.1.1/lib/swagger/docs/generator.rb:105:in `block in write_doc'
/Users/cdcooksey/.rvm/gems/ruby-2.0.0-p195/gems/swagger-docs-0.1.1/lib/swagger/docs/generator.rb:96:in `each'
/Users/cdcooksey/.rvm/gems/ruby-2.0.0-p195/gems/swagger-docs-0.1.1/lib/swagger/docs/generator.rb:96:in `write_doc'
/Users/cdcooksey/.rvm/gems/ruby-2.0.0-p195/gems/swagger-docs-0.1.1/lib/swagger/docs/generator.rb:71:in `block in write_docs'
/Users/cdcooksey/.rvm/gems/ruby-2.0.0-p195/gems/swagger-docs-0.1.1/lib/swagger/docs/generator.rb:69:in `each'
/Users/cdcooksey/.rvm/gems/ruby-2.0.0-p195/gems/swagger-docs-0.1.1/lib/swagger/docs/generator.rb:69:in `write_docs'
/Users/cdcooksey/.rvm/gems/ruby-2.0.0-p195/gems/swagger-docs-0.1.1/lib/tasks/swagger.rake:5:in `block (2 levels) in <top (required)>'
/Users/cdcooksey/.rvm/gems/ruby-2.0.0-p195/gems/rake-10.1.1/lib/rake/task.rb:236:in `call'
/Users/cdcooksey/.rvm/gems/ruby-2.0.0-p195/gems/rake-10.1.1/lib/rake/task.rb:236:in `block in execute'
/Users/cdcooksey/.rvm/gems/ruby-2.0.0-p195/gems/rake-10.1.1/lib/rake/task.rb:231:in `each'
/Users/cdcooksey/.rvm/gems/ruby-2.0.0-p195/gems/rake-10.1.1/lib/rake/task.rb:231:in `execute'
/Users/cdcooksey/.rvm/gems/ruby-2.0.0-p195/gems/rake-10.1.1/lib/rake/task.rb:175:in `block in invoke_with_call_chain'
/Users/cdcooksey/.rvm/rubies/ruby-2.0.0-p195/lib/ruby/2.0.0/monitor.rb:211:in `mon_synchronize'
/Users/cdcooksey/.rvm/gems/ruby-2.0.0-p195/gems/rake-10.1.1/lib/rake/task.rb:168:in `invoke_with_call_chain'
/Users/cdcooksey/.rvm/gems/ruby-2.0.0-p195/gems/rake-10.1.1/lib/rake/task.rb:161:in `invoke'
/Users/cdcooksey/.rvm/gems/ruby-2.0.0-p195/gems/rake-10.1.1/lib/rake/application.rb:149:in `invoke_task'
/Users/cdcooksey/.rvm/gems/ruby-2.0.0-p195/gems/rake-10.1.1/lib/rake/application.rb:106:in `block (2 levels) in top_level'
/Users/cdcooksey/.rvm/gems/ruby-2.0.0-p195/gems/rake-10.1.1/lib/rake/application.rb:106:in `each'
/Users/cdcooksey/.rvm/gems/ruby-2.0.0-p195/gems/rake-10.1.1/lib/rake/application.rb:106:in `block in top_level'
/Users/cdcooksey/.rvm/gems/ruby-2.0.0-p195/gems/rake-10.1.1/lib/rake/application.rb:115:in `run_with_threads'
/Users/cdcooksey/.rvm/gems/ruby-2.0.0-p195/gems/rake-10.1.1/lib/rake/application.rb:100:in `top_level'
/Users/cdcooksey/.rvm/gems/ruby-2.0.0-p195/gems/rake-10.1.1/lib/rake/application.rb:78:in `block in run'
/Users/cdcooksey/.rvm/gems/ruby-2.0.0-p195/gems/rake-10.1.1/lib/rake/application.rb:165:in `standard_exception_handling'
/Users/cdcooksey/.rvm/gems/ruby-2.0.0-p195/gems/rake-10.1.1/lib/rake/application.rb:75:in `run'
/Users/cdcooksey/.rvm/gems/ruby-2.0.0-p195/gems/rake-10.1.1/bin/rake:33:in `<top (required)>'
/Users/cdcooksey/.rvm/gems/ruby-2.0.0-p195/bin/rake:23:in `load'
/Users/cdcooksey/.rvm/gems/ruby-2.0.0-p195/bin/rake:23:in `<main>'
/Users/cdcooksey/.rvm/gems/ruby-2.0.0-p195/bin/ruby_executable_hooks:15:in `eval'
/Users/cdcooksey/.rvm/gems/ruby-2.0.0-p195/bin/ruby_executable_hooks:15:in `<main>'
Tasks: TOP => swagger:docs

wiki explanation of how/why to use machine-readable api descriptions

Let's make it easier for institutional champions to... champion.

I would do this, if I could read or write.

enum support for parameters

Is there a way of specifying a list of valid values for a parameter, like on this swagger-core wiki page? If so, can you add an example use to the README?

Filtered path parameters and api_extension_type generate incorrect JSON

Filtering out path parameters in #22 surfaced another bug—when the api_extension_type config is given it seems to be generating incorrect JSON output:

Gettng: "path": "projects/{id.json}"
Should be getting: "path": "projects/{id}.json"

For this api:

param :path, :id, :integer, :required, 'Project ID.'

It would also be really helpful to have some logging that says "Filtered out parameter 'id' because it was not present in path "path": "projects/{id.json}"." After #22, things just disappeared from the JSON output and it required digging around to figure out why.

uninitialized constant V1::AuthClaimsController

I have my controllers nested in a module that pertains to the API version because I use the Versionist gem. For example:

module V1
  class BuildsController < ApplicationController
    swagger_controller :builds, 'Software Builds'

    def index
      # blah blah
    end

    swagger_api :index do
      summary 'List all software builds.'
      param :query, :access_token, :string, :required, 'Authentication'
      param :query, :order, :string, :optional, 'Column name to sort results'
      param :query, :direction, :string, :optional, 'Sort direction'
      param :query, :page, :integer, :optional, 'Page number'
      param :query, :per_page, :integer, :optional, 'Number of results per page'
      response :unauthorized
    end
  end
end

When I try to generate Swagger docs, I get this error:

% rake swagger:docs
rake aborted!
uninitialized constant V1::AuthClaimsController
/Users/me/.rvm/gems/ruby-2.0.0-p353/gems/activesupport-4.0.1/lib/active_support/inflector/methods.rb:228:in `const_get'
/Users/me/.rvm/gems/ruby-2.0.0-p353/gems/activesupport-4.0.1/lib/active_support/inflector/methods.rb:228:in `block in constantize'
/Users/me/.rvm/gems/ruby-2.0.0-p353/gems/activesupport-4.0.1/lib/active_support/inflector/methods.rb:224:in `each'
/Users/me/.rvm/gems/ruby-2.0.0-p353/gems/activesupport-4.0.1/lib/active_support/inflector/methods.rb:224:in `inject'
/Users/me/.rvm/gems/ruby-2.0.0-p353/gems/activesupport-4.0.1/lib/active_support/inflector/methods.rb:224:in `constantize'
/Users/me/.rvm/gems/ruby-2.0.0-p353/gems/activesupport-4.0.1/lib/active_support/core_ext/string/inflections.rb:66:in `constantize'
/Users/me/.rvm/gems/ruby-2.0.0-p353/gems/swagger-docs-0.1.1/lib/swagger/docs/generator.rb:98:in `block in write_doc'
/Users/me/.rvm/gems/ruby-2.0.0-p353/gems/swagger-docs-0.1.1/lib/swagger/docs/generator.rb:96:in `each'
/Users/me/.rvm/gems/ruby-2.0.0-p353/gems/swagger-docs-0.1.1/lib/swagger/docs/generator.rb:96:in `write_doc'
/Users/me/.rvm/gems/ruby-2.0.0-p353/gems/swagger-docs-0.1.1/lib/swagger/docs/generator.rb:71:in `block in write_docs'
/Users/me/.rvm/gems/ruby-2.0.0-p353/gems/swagger-docs-0.1.1/lib/swagger/docs/generator.rb:69:in `each'
/Users/me/.rvm/gems/ruby-2.0.0-p353/gems/swagger-docs-0.1.1/lib/swagger/docs/generator.rb:69:in `write_docs'
/Users/me/.rvm/gems/ruby-2.0.0-p353/gems/swagger-docs-0.1.1/lib/tasks/swagger.rake:5:in `block (2 levels) in <top (required)>'
/Users/me/.rvm/gems/ruby-2.0.0-p353/bin/ruby_executable_hooks:15:in `eval'
/Users/me/.rvm/gems/ruby-2.0.0-p353/bin/ruby_executable_hooks:15:in `<main>'
Tasks: TOP => swagger:docs
(See full trace by running task with --trace)

This might also be an interaction with the Doorkeeper gem.