adrian-gomez / swaggard Goto Github PK

View Code? Open in Web Editor NEW

54.0 54.0 38.0 2.78 MB

Add Swagger documentation to your Rails REST endpoints.

License: MIT License

Ruby 1.58% JavaScript 95.32% CSS 0.05% HTML 0.10% SCSS 2.95%

swaggard's People

Contributors

Stargazers

Watchers

swaggard's Issues

Conflict ActiveAdmin and Swaggard

Could someone guide me to find the solution?

The project was created with Rails 5 API.

The gem swaggard continues to function normally, but gem activeadmin is no longer working. The error that is happening is as follows:

Sprockets :: Rails :: Helper :: AssetNotFound at / admin / login
The asset "active_admin.css" is not present in the asset pipeline

Here are also the gens I'm using in the project:

GemFile

gem 'rails', '5.1.4'
gem 'pg', '~> 0.18'
gem 'puma', '~> 3.7'
gem 'rack-cors'
gem 'rack-attack'
gem 'devise'
gem 'omniauth-facebook', '4.0.0'
gem 'koala'
gem 'simple_token_authentication', '~> 1.0'
gem 'dotenv-rails'
gem 'active_model_serializers', require: true
gem 'figaro'
gem 'paranoia', '~> 2.2'
gem 'activeadmin', github: 'activeadmin'
gem 'swaggard'
gem 'inherited_resources', git:'https://github.com/activeadmin/inherited_resources'

group :development, :test do
  gem 'ffaker'
  gem 'faker'
  gem 'rspec-rails'
  gem 'rspec-core'
  gem 'simplecov', :require => false
  gem 'rubycritic', :require => false
  gem 'capybara'
  gem 'spork', '~> 1.0rc'
  gem 'factory_girl_rails'
  gem 'annotate'
  gem 'letter_opener'
  gem 'byebug', platforms: [:mri, :mingw, :x64_mingw]
end

group :development do
  gem 'web-console', '>= 3.3.0'
  gem 'better_errors'
  gem 'listen', '~> 3.1.5'
  gem 'spring'
  gem 'spring-watcher-listen', '~> 2.0.0'
  gem 'rack-mini-profiler'
  gem 'binding_of_caller'
  gem 'brakeman', :require => false
  gem 'rubocop', require: false
  gem 'sprockets', '~> 3.0'
end

# Windows does not include zoneinfo files, so bundle the tzinfo-data gem
gem 'tzinfo-data', platforms: [:mingw, :mswin, :x64_mingw, :jruby]

# Autodeploy
gem 'capistrano', '~> 3.7', '>= 3.7.1'
gem 'capistrano-rails', '~> 1.2'
gem 'capistrano-passenger', '~> 0.2.0'
gem 'capistrano-rbenv', '~> 2.1'
gem 'capistrano-bundler', '~> 1.3'

Assets broken with `master` and Rails 5

Installed swaggard and assets are no longer working.

@elpic also mentions this in #11

https failing

As seen in issue swagger-api/swagger-ui#1957

Is there a way to change is in the implementation of swagger-ui?

How to deal with JSON root keys?

Case in point, my serializer returns JSON with a root key, because I'm using the ActiveModel Serializers JSON adapter:

ActiveModelSerializers.config.adapter = :json

The PingsController#ping action:

class PingsController < BaseController

  # Responds to pings
  #
  # @response_class PingResponseSerializer
  def ping
    @ping_response = PingResponse.new
    render json: @ping_response
  end
end

This is my PingResponseSerializer:

# @attr [string] text
# @attr [string] status
class PingResponseSerializer < ActiveModel::Serializer
  attribute(:text) { "PONG" }
  attribute(:status) { "ok" }
end

Which results in the following JSON output:

{
  "ping_response": {
    "text": "PONG",
    "status": "ok"
  }
}

However, this is the example output:

{
  "text": "string",
  "status": "string"
}

Question: how do I get swagger/swaggard to understand the JSON root key?

Question: Is it possible to add a UUID definition type?

All objects returned by my API I'm have UUIDs for their IDs, and I am wondering if there is a way to define a UUID primitive type in Swaggard?

I could define these as # @attr [string] id (which I am currently doing) but would rather use # @attr [uuid] id some it gives a bit more feedback as to what the ID format should be.

It mentions in the README under primitive types "When one of these types is given Swaggard will handle them directly instead of searching for a definition" so I'm guessing that it is possible to add custom definitions, I'm just not sure how to go about this.

Question: Can I use this without active_model_serializers ?

Hi, I am new to rails, can this library used without active_model_serializers, our project is using https://github.com/nesquena/rabl.

tag to skip parsing subclass inside Rails controller

class BamController < ActionController::Base
  # @skip parsing Bam
  class Bam
  end
end

anyway to skip parsing BamController::Bam?

Thanks.

Comment paragraphs with newlines (a la 80-char limit on line length) causes superfluous newlines when documentation is viewed

NOTE: I am still new to Ruby / Rails and Javascript development, so please
take these notes with a grain of salt.

According to the Ruby style guide, lines should be limited to 80 characters
(https://github.com/bbatsov/ruby-style-guide#80-character-limits). We hold to
this standard both for code and for comments, so a paragraph in a class or
method's documentation may span multiple lines.

The problem arises when we view our Swaggard-generated API
documentation --- the generated documentation itself follows the 80-char line
length, rather than being word-wrapped according to the size of the text area
as expected. This occurs in both the Swaggard implementation of swagger-ui and
in swagger_engine (https://github.com/batdevis/swagger_engine).

I believe that this is caused by two lines of code:

https://github.com/moove-it/swaggard/blob/master/lib/swaggard/swagger/operation.rb#L24
Because the documentation already contains newlines, this causes two
\n characters to appear in the JSON. The Markdown engine interprets
this to indicate separate paragraphs, causing each line in the
generated HTML to be wrapped in <p> tags.
This affects both the swagger_engine and the Swaggard
implementations of swagger-ui, as this impacts the JSON file that is
used to display the documentation.
Joining the lines on the empty string appears to remedy this problem;
if so, then this is a necessary and sufficient solution for viewing
the documentation in swagger_engine. However, it is not a sufficient
solution for the Swaggard viewer (though still necessary); see below.
https://github.com/moove-it/swaggard/blob/master/app/assets/javascripts/swaggard/swagger-ui.js#L1185
From what I can tell, this line is replacing every newline with
<br /> before the Markdown engine processes the text,
circumventing the Markdown rules for handling single vs. multiple
newline characters.
It does not appear that either swagger-ui or swagger_engine implement
this logic, so only the Swaggard implementation of swagger-ui is
affected.
Commenting out this conditional appears a necessary (and, combined
with the above change, sufficient) change to solve the problem with
the Swaggard viewer.

I will submit a pull request with these two changes made. From what I can
tell, they should not negatively impact anything else in the code, but I am
obviously not as familiar with the code base as you are. :-)

On one final note, it may be worthwhile to document the expected formatting of
comments for classes, methods, etc. For example, it appears that controller
classes should only be given a single comment line, as any additional
paragraphs are concatenated into the description of the API section.
Furthermore, the documentation for a single method appears to expect a single
initial line which is taken as the summary, with all additional lines taken as
the "Implementation Notes." I wouldn't consider these to be problems or
errors per se, but it would be good to have these expectations documented for
users of this project.

(Also, thank you for creating this --- I definitely like the combination of
YARD-style documentation and the Swagger presentation UI!)

Array Object

Hi! I am now using this gem for my API. However, I'm having a hard time adding some parameters like array object.

This is my sample parameter on postman and I want to try this on swaggard.

But I ended up having this:

and this is my codes

#products_controller.rb

# Create product
#
# @body_parameter [string] sku
# @body_parameter [array] product_category_attributes
def create
product = Product.new(product_params)
if product.save
@http_response = product
@http_status = 200
else
@http_response = product.errors
end
render :json => @http_response, :status => @http_status
end

# strong parameters
def product_params
params.permit(
:sku,
product_category_attributes: [ :id, :category_id, :product_id,:_destroy ]
)
end

Looking forward for the fast response. Thank you!

Header per request basis

Is there a way for sending headers pertaining to a particular request. For example a user sign in authtoken ?

Document scoping - allow an array of controllers

controllers_path is a string, do we have any alternative to support multiple controllers? For example I want to have list of controllers (which is not so easy to extract in a single regex string) to be documented and not all controllers in the app.

config.controllers_path = "#{Rails.root}/app/controllers/api/**/*.rb"

Missing security definitions in json

When using only the json you miss the securityDefinitions when you define https://github.com/adrian-gomez/swaggard#authentication

Looking into the code these config variable are only used in the html generator. Can they also be exposed in the json?

Documentation on this: https://swagger.io/docs/specification/2-0/authentication/

The asset "application.css" is not present in the asset pipeline.

Create test rails application and add swaggard gem to gemfile (swaggard configuration doesn't matter, it happens anyway). Any route opening causes error "The asset "application.css" is not present in the asset pipeline."
There is stack trace

app/views/layouts/application.html.erb where line #7 raised:

5    <%= csrf_meta_tags %>
6
7    <%= stylesheet_link_tag    'application', media: 'all', 'data-turbolinks-track': 'reload' %>
8    <%= javascript_include_tag 'application', 'data-turbolinks-track': 'reload' %>
9  </head>

And it's my gemfile

source 'https://rubygems.org'

git_source(:github) do |repo_name|
  repo_name = "#{repo_name}/#{repo_name}" unless repo_name.include?("/")
  "https://github.com/#{repo_name}.git"
end

gem 'rails', '~> 5.1.2'
gem 'sqlite3'
gem 'puma', '~> 3.7'
gem 'sass-rails', '~> 5.0'
gem 'uglifier', '>= 1.3.0'

gem 'swaggard'

gem 'coffee-rails', '~> 4.2'
gem 'turbolinks', '~> 5'
gem 'jbuilder', '~> 2.5'

group :development, :test do
  gem 'byebug', platforms: [:mri, :mingw, :x64_mingw]
  gem 'capybara', '~> 2.13'
  gem 'selenium-webdriver'
end

group :development do
  gem 'web-console', '>= 3.3.0'
  gem 'listen', '>= 3.0.5', '< 3.2'
  gem 'spring'
  gem 'spring-watcher-listen', '~> 2.0.0'
end

gem 'tzinfo-data', platforms: [:mingw, :mswin, :x64_mingw, :jruby]

Support for Rails 5

Swaggard is a util gem but doesn´t support for Rails 5

error after bundle

Rails 5.0.0.rc2
ruby 2.3.1p112

when I add gem 'swaggard' and bundle

error when 'rails s'
/usr/local/lib/ruby/gems/2.3.0/gems/actionpack-5.0.0.rc2/lib/action_dispatch/middleware/stack.rb:96:in `push': can't modify frozen Array (RuntimeError)

everything ok when remove gem

error message

Exiting
/usr/local/lib/ruby/gems/2.3.0/gems/actionpack-5.0.0.rc2/lib/action_dispatch/middleware/stack.rb:96:in `push': can't modify frozen Array (RuntimeError)
	from /usr/local/lib/ruby/gems/2.3.0/gems/actionpack-5.0.0.rc2/lib/action_dispatch/middleware/stack.rb:96:in `use'
	from /usr/local/lib/ruby/gems/2.3.0/gems/rails_admin-1.1.0/lib/rails_admin/engine.rb:27:in `block in <class:Engine>'
	from /usr/local/lib/ruby/gems/2.3.0/gems/railties-5.0.0.rc2/lib/rails/initializable.rb:30:in `instance_exec'
	from /usr/local/lib/ruby/gems/2.3.0/gems/railties-5.0.0.rc2/lib/rails/initializable.rb:30:in `run'
	from /usr/local/lib/ruby/gems/2.3.0/gems/railties-5.0.0.rc2/lib/rails/initializable.rb:55:in `block in run_initializers'
	from /usr/local/Cellar/ruby/2.3.1/lib/ruby/2.3.0/tsort.rb:228:in `block in tsort_each'
	from /usr/local/Cellar/ruby/2.3.1/lib/ruby/2.3.0/tsort.rb:350:in `block (2 levels) in each_strongly_connected_component'
	from /usr/local/Cellar/ruby/2.3.1/lib/ruby/2.3.0/tsort.rb:431:in `each_strongly_connected_component_from'
	from /usr/local/Cellar/ruby/2.3.1/lib/ruby/2.3.0/tsort.rb:349:in `block in each_strongly_connected_component'
	from /usr/local/Cellar/ruby/2.3.1/lib/ruby/2.3.0/tsort.rb:347:in `each'
	from /usr/local/Cellar/ruby/2.3.1/lib/ruby/2.3.0/tsort.rb:347:in `call'
	from /usr/local/Cellar/ruby/2.3.1/lib/ruby/2.3.0/tsort.rb:347:in `each_strongly_connected_component'
	from /usr/local/Cellar/ruby/2.3.1/lib/ruby/2.3.0/tsort.rb:226:in `tsort_each'
	from /usr/local/Cellar/ruby/2.3.1/lib/ruby/2.3.0/tsort.rb:205:in `tsort_each'
	from /usr/local/lib/ruby/gems/2.3.0/gems/railties-5.0.0.rc2/lib/rails/initializable.rb:54:in `run_initializers'
	from /usr/local/lib/ruby/gems/2.3.0/gems/railties-5.0.0.rc2/lib/rails/application.rb:352:in `initialize!'
	from /Users/sky/project/Amazingtutor/config/environment.rb:7:in `<top (required)>'
	from /usr/local/lib/ruby/gems/2.3.0/gems/activesupport-5.0.0.rc2/lib/active_support/dependencies.rb:293:in `require'
	from /usr/local/lib/ruby/gems/2.3.0/gems/activesupport-5.0.0.rc2/lib/active_support/dependencies.rb:293:in `block in require'
	from /usr/local/lib/ruby/gems/2.3.0/gems/activesupport-5.0.0.rc2/lib/active_support/dependencies.rb:259:in `load_dependency'
	from /usr/local/lib/ruby/gems/2.3.0/gems/activesupport-5.0.0.rc2/lib/active_support/dependencies.rb:293:in `require'
	from /Users/sky/project/Amazingtutor/config.ru:3:in `block in <main>'
	from /usr/local/lib/ruby/gems/2.3.0/gems/rack-2.0.1/lib/rack/builder.rb:55:in `instance_eval'
	from /usr/local/lib/ruby/gems/2.3.0/gems/rack-2.0.1/lib/rack/builder.rb:55:in `initialize'
	from /Users/sky/project/Amazingtutor/config.ru:in `new'
	from /Users/sky/project/Amazingtutor/config.ru:in `<main>'
	from /usr/local/lib/ruby/gems/2.3.0/gems/rack-2.0.1/lib/rack/builder.rb:49:in `eval'
	from /usr/local/lib/ruby/gems/2.3.0/gems/rack-2.0.1/lib/rack/builder.rb:49:in `new_from_string'
	from /usr/local/lib/ruby/gems/2.3.0/gems/rack-2.0.1/lib/rack/builder.rb:40:in `parse_file'
	from /usr/local/lib/ruby/gems/2.3.0/gems/rack-2.0.1/lib/rack/server.rb:318:in `build_app_and_options_from_config'
	from /usr/local/lib/ruby/gems/2.3.0/gems/rack-2.0.1/lib/rack/server.rb:218:in `app'
	from /usr/local/lib/ruby/gems/2.3.0/gems/railties-5.0.0.rc2/lib/rails/commands/server.rb:59:in `app'
	from /usr/local/lib/ruby/gems/2.3.0/gems/rack-2.0.1/lib/rack/server.rb:353:in `wrapped_app'
	from /usr/local/lib/ruby/gems/2.3.0/gems/railties-5.0.0.rc2/lib/rails/commands/server.rb:124:in `log_to_stdout'
	from /usr/local/lib/ruby/gems/2.3.0/gems/railties-5.0.0.rc2/lib/rails/commands/server.rb:77:in `start'
	from /usr/local/lib/ruby/gems/2.3.0/gems/railties-5.0.0.rc2/lib/rails/commands/commands_tasks.rb:90:in `block in server'
	from /usr/local/lib/ruby/gems/2.3.0/gems/railties-5.0.0.rc2/lib/rails/commands/commands_tasks.rb:85:in `tap'
	from /usr/local/lib/ruby/gems/2.3.0/gems/railties-5.0.0.rc2/lib/rails/commands/commands_tasks.rb:85:in `server'
	from /usr/local/lib/ruby/gems/2.3.0/gems/railties-5.0.0.rc2/lib/rails/commands/commands_tasks.rb:49:in `run_command!'
	from /usr/local/lib/ruby/gems/2.3.0/gems/railties-5.0.0.rc2/lib/rails/commands.rb:18:in `<top (required)>'
	from /Users/sky/project/Amazingtutor/bin/rails:9:in `require'
	from /Users/sky/project/Amazingtutor/bin/rails:9:in `<top (required)>'
	from /usr/local/lib/ruby/gems/2.3.0/gems/spring-2.0.0/lib/spring/client/rails.rb:28:in `load'
	from /usr/local/lib/ruby/gems/2.3.0/gems/spring-2.0.0/lib/spring/client/rails.rb:28:in `call'
	from /usr/local/lib/ruby/gems/2.3.0/gems/spring-2.0.0/lib/spring/client/command.rb:7:in `call'
	from /usr/local/lib/ruby/gems/2.3.0/gems/spring-2.0.0/lib/spring/client.rb:30:in `run'
	from /usr/local/lib/ruby/gems/2.3.0/gems/spring-2.0.0/bin/spring:49:in `<top (required)>'
	from /usr/local/lib/ruby/gems/2.3.0/gems/spring-2.0.0/lib/spring/binstub.rb:31:in `load'
	from /usr/local/lib/ruby/gems/2.3.0/gems/spring-2.0.0/lib/spring/binstub.rb:31:in `<top (required)>'
	from /usr/local/lib/ruby/site_ruby/2.3.0/rubygems/core_ext/kernel_require.rb:68:in `require'
	from /usr/local/lib/ruby/site_ruby/2.3.0/rubygems/core_ext/kernel_require.rb:68:in `require'
	from /Users/sky/project/Amazingtutor/bin/spring:13:in `<top (required)>'
	from bin/rails:3:in `load'
	from bin/rails:3:in `<main>'

Question about jsonb

One of the models in my application has an attribute with type jsonb. The serializer for that model returns several attributes including the one that is of jsonb type. How do I document this with Swaggard? There is no object type as far as I can tell so I'm at a bit of a loss.

Thanks.

Documentation generated for one controller and not another

I'm trying to add my UserRequestController to the documentation but nothing is showing up. When I do the same in another controller that inherits from the same base it works just fine.

ApiUserRequestsController (Not rendering in swagger)

# frozen_string_literal: true

# @tag Users
# Users related resources of the  API
class Api::V1::ApiUserRequestsController < Api::V1::APIController

ApiCertificateRequestsController (Is rendering in swagger)

# frozen_string_literal: true

# @tag Certificates
# Certificate related resources of the API
class Api::V1::ApiCertificateRequestsController < Api::V1::APIController

Configure for SSL only sites?

This is working great for localhost, but when I push it to staging which only allows SSL connections it still makes requests to http.

I tried setting api_base_path to:

config.api_base_path = 'https://api.example.com'

But it seems like api_base_path is getting appended to the current host:

http://localhost:3000https://api.example.com/widgets

Any ideas?

BTW: I am currently using the rails-5 branch #15, I doubt that is causing the issue - I will try to install current stable branch and double check that as well.

Bug: NS_ERROR_MALFORMED_URI when clicking "Try it out!"

I'm getting an NS_ERROR_MALFORMED_URI error when clicking "Try it out!" on an API action.

I think it might have something to do with the URL then attempted being set to:
localhost:3000/swagger#!/api%2Fattachments/read_only_token
with %2F being a part of the url after the url parsing, when it should probably be / instead.

I'm using Firefox 45.7.0

Chrome Version 55.0.2883.95 (64-bit) gave this error:

Uncaught DOMException: Failed to execute 'open' on 'XMLHttpRequest': Invalid URL
    at Request.end (http://localhost:3000/assets/swaggard/swagger-ui-6d108ff7325bed701fc9c9c3caeb6dc3.js?body=1:20914:9)
    at SuperagentHttpClient.execute (http://localhost:3000/assets/swaggard/swagger-ui-6d108ff7325bed701fc9c9c3caeb6dc3.js?body=1:4435:5)
    at module.exports.SwaggerHttp.execute (http://localhost:3000/assets/swaggard/swagger-ui-6d108ff7325bed701fc9c9c3caeb6dc3.js?body=1:4258:12)
    at module.exports.Operation.execute (http://localhost:3000/assets/swaggard/swagger-ui-6d108ff7325bed701fc9c9c3caeb6dc3.js?body=1:7548:30)
    at C.n.submitOperation (http://localhost:3000/assets/swaggard/swagger-ui-6d108ff7325bed701fc9c9c3caeb6dc3.js?body=1:23311:27)
    at HTMLInputElement.r (http://localhost:3000/assets/swaggard/lib/lodash.min-748e65e6387ba21a89990d57e17ef20c.js?body=1:1:10605)
    at HTMLLIElement.dispatch (http://localhost:3000/assets/swaggard/lib/jquery-1.8.0.min-ff0dd4be3e0f3362ad5970d13fe9ccad.js?body=1:2:5616)
    at HTMLLIElement.s (http://localhost:3000/assets/swaggard/lib/jquery-1.8.0.min-ff0dd4be3e0f3362ad5970d13fe9ccad.js?body=1:2:1585)
Request.end @ client.js:812
SuperagentHttpClient.execute @ http.js:292
SwaggerHttp.execute @ http.js:115
Operation.execute @ operation.js:891
submitOperation @ OperationView.js:455
r @ lodash.min-748e65e….js?body=1:1
dispatch @ jquery-1.8.0.min-ff0dd4b….js?body=1:2
s @ jquery-1.8.0.min-ff0dd4b….js?body=1:2

Any way to limit which controllers appear as part of the API doc

Thanks very much for writing Swaggard. I wasn't having much luck assembling the various other swagger related gems. This one worked straight out of the box.

I'm probably missing something but it seems that Swaggard will always expose documentation for everything under /app/controllers. Is there any way I could limit it so that it only generated docs for say /app/controllers/api ?

Thanks

JSON doesn't include all the endpoints.

If you have more than one endpoints using same controller#action, the JSON object created contains only the last one.

Swaggard hash param usage on Rails 5

Hello,

I'm not sure how to correctly use the hash feature. Params for my controllers have to be inside of a hash, like so {"talent"=>{"name":"Some Person"}}, where talent is the name of the hash. I'm running rails 5. The comments I have for the create method look like this:

#Creates a talent record
#@body_parameter [hash] talent

The resultant swagger interface looks weird. it looks like this:

Notice the "dash" signs in place of a body field. How do I get the body to show?

On the right hand side, I'd like the talent hash to be populated with keys and values. Is there a way to currently achieve that? I tried a few tricks, but couldn't get the "name":"Some Person" key-value pair to show up there.

Thank you!

adrian-gomez / swaggard Goto Github PK

swaggard's People

Contributors

Stargazers

Watchers

Forkers

swaggard's Issues

ApiUserRequestsController (Not rendering in swagger)

ApiCertificateRequestsController (Is rendering in swagger)

Recommend Projects

Recommend Topics

Recommend Org