richhollis / swagger-docs Goto Github PK
View Code? Open in Web Editor NEWGenerates swagger-ui json files for Rails APIs with a simple DSL.
License: MIT License
Generates swagger-ui json files for Rails APIs with a simple DSL.
License: MIT License
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"
}
}
Is there a way to define references?
https://github.com/wordnik/swagger-spec/blob/master/versions/1.2.md#433-data-type-fields
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?
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.
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
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?
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.
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."
how to define response class?
Like this
http://petstore.swagger.wordnik.com/#!/pet/getPetById
Similar to the info the top of this page.
http://petstore.swagger.wordnik.com/
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
After I run "rake swagger:docs" for the swagger docs sample, it showed : "1.0: 3 processed / 2 skipped".
What does it mean?
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)>'
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 method
swagger_controller'` unless I restart the development server.
Am I configuring something wrong for this to happen?
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?
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.
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!
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.
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
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?
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.
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!
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"
}
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
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
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!
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
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.
Let's make it easier for institutional champions to... champion.
I would do this, if I could read or write.
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:in
each'
/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:in
constantize'
/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'
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?
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!
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?
I have generated api, but it doesn't create index.html to view it.
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.
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.
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!
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?
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
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?
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>'
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
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?
Hi! Any thoughts for generation of response object in an api endpoint?
edit: also called, the response class
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?
resources :services do
post 'report', on: :member, to: 'reports#create'
end
I wonder if there is a way I can do something similar to the Java counterpart.
response = Person.class
Thanks!
I need all swagger api actions to set a custom header to my server. How do I do this?
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.
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
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?
A declarative, efficient, and flexible JavaScript library for building user interfaces.
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google ❤️ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.