Some clarifications of the documentation

[obromios]

In the README, there is an example, however I found some aspects of this confusing:

• Twice there is a line expect(response_body).to eq(<response>), but the angle brackets do not appear to be valid?
• It uses the route_summary and authentication keywords, but these only seem valid for the open_api format.
• It does not include the lines:

require 'rails_helper'
require 'rspec_api_documentation/dsl'

• it would be clearer to put #spec/acceptance/orders_spec.rb at the top of the example to make it clear where it should sit.
• In this example, and the examples in the examples folder, an exception is triggered by giving an incorrect id. It would be also of interest to show how to generate an exception when there is a missing parameter. I am having trouble doing this, for instance, using two different versions of let(:raw_post) (one with all the required parameters and one with a required parameter missing) does not seem to work.
• In the section on Viewers>Gemfile, would it be clearer to mention the apitome gem as well, currently it gives the impression that the raddocs gem gives access to apitome functionality. Perhaps this would be clearer

gem 'raddocs'

or

gem 'apitome'

[obromios]

Also, when I run rake doc:generate I get an error: An error occurred while loading ./spec/acceptance/matches_api_spec.rb.

Failure/Error:
  Shoulda::Matchers.configure do |config|
    config.integrate do |with|
      with.test_framework :rspec
      with.library :rails
    end
  end

NameError:
  uninitialized constant Shoulda

whereas rails docs:generate works fine. Perhaps for rails 5.1 the instruction should be rails docs:generate?

[obromios]

Sorry for all the suggestions, but I am finding the gem very useful, but I think that updating the documentation would help others to find it easier to use.

I notice that your rubygems version is almost one year out of date. It looks like there have been a number off issues fixed since then. If you do not have time to do a new release, them perhaps you can change the documentation to indicate the last solid commit e.g.

gem 'rspec_api_documentation', git: 'https://github.com/zipmark/rspec_api_documentation.git', ref: 'xyz'

Also it would be useful to have a CHANGELOG file so people can work out the last solid commit from that.

[oestrich]

I'm not sure what's up with your Shoulda issue, my guess is your acceptance_helper.rb is off slightly and not including it?

As far as any docs are concerned, PRs are welcome! We have this wiki page https://github.com/zipmark/rspec_api_documentation/wiki/Changes along with releases on github to tag when I push a new version to rubygems.

Typically there isn't very much activity on RAD so going this long without a release is sort of normal at where its at. I should cut a new version soon since we have that large PR for openapi finally get merged. (This is also how I typically cut a new release, someone asks for it because I forget after merging things)

[obromios]

A new version would be good. I will try to do a PR by the end of this week.

regards

Chris

On Thu, Jul 26, 2018 at 11:17 PM Eric Oestrich [email protected] wrote:

I'm not sure what's up with your Shoulda issue, my guess is your acceptance_helper.rb is off slightly and not including it?

As far as any docs are concerned, PRs are welcome! We have this wiki page https://github.com/zipmark/rspec_api_documentation/wiki/Changes along with releases on github to tag when I push a new version to rubygems.

Typically there isn't very much activity on RAD so going this long without a release is sort of normal at where its at. I should cut a new version soon since we have that large PR for openapi finally get merged. (This is also how I typically cut a new release, someone asks for it because I forget after merging things)

— You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub https://github.com/zipmark/rspec_api_documentation/issues/386#issuecomment-408093877, or mute the thread https://github.com/notifications/unsubscribe-auth/ABU2mbk3SpaXBcfyE-zFJQT0HcmrH-yqks5uKcFTgaJpZM4Vfm5M .