rspec-rails-api 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 0d84f33b2eb3f005afce4a2712e2fd3523687f5ba098573d93e386439aa97639
+  data.tar.gz: e013cc905ed66797cd78c6d6c833c87ba30e939a0c12b950cb1209639789a3fd
+SHA512:
+  metadata.gz: 32a8012f525f7319555e5aada0b1019e37939461034522193e939a2a028a3fb5897a133e0fb5fdd93a4ef8b77d3a62d2092884bae9c6e3194e50da8b5bd3572d
+  data.tar.gz: 5703b53a8d61d35c4e8124e615056da5c909bbe47e96fe9aeeb5362479a80db8d5c6999094ebb06d8502d1937f3520908d6554a66e3360ffb43d747c962d1021

data/.gitignore

@@ -0,0 +1,14 @@
+/.bundle/
+/.yardoc
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+
+# rspec failure tracking
+.rspec_status
+
+# Ignore lockfile for Gemfile
+Gemfile.lock

data/.gitlab-ci.yml

@@ -0,0 +1,36 @@
+---
+image: ruby:2.4
+
+stages:
+  - prepare
+  - test
+
+bundle:
+  stage: prepare
+  script:
+    - bundle install --path='vendor/bundle'
+  artifacts:
+    untracked: true
+    expire_in: 1 hour
+    paths:
+      - 'vendor/'
+  cache:
+    untracked: true
+    paths:
+      - 'vendor/'
+
+rubocop:
+  stage: test
+  script:
+    - bundle install --path='vendor/bundle'
+    - bundle exec rubocop
+  dependencies:
+    - bundle
+
+rspec:
+  stage: test
+  script:
+    - bundle install --path='vendor/bundle'
+    - bundle exec rspec
+  dependencies:
+    - bundle

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,29 @@
+---
+require:
+  - rubocop-performance
+
+Metrics/BlockLength:
+  Exclude:
+    - examples/**/*.rb
+    - rspec-rails-api.gemspec
+    - spec/**/*_spec.rb
+
+Metrics/LineLength:
+  Max: 120
+  Exclude:
+    - spec/**/*_spec.rb
+
+Naming/UncommunicativeMethodParamName:
+  AllowedNames:
+    - of
+
+Layout/AlignHash:
+  EnforcedColonStyle: table
+  EnforcedHashRocketStyle: table
+
+Style/TrailingCommaInArrayLiteral:
+  EnforcedStyleForMultiline: comma
+
+Style/TrailingCommaInHashLiteral:
+  EnforcedStyleForMultiline: comma
+

data/.travis.yml

@@ -0,0 +1,7 @@
+---
+sudo: false
+language: ruby
+cache: bundler
+rvm:
+  - 2.5.1
+before_install: gem install bundler -v 1.17.0

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,74 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+In the interest of fostering an open and welcoming environment, we as
+contributors and maintainers pledge to making participation in our project and
+our community a harassment-free experience for everyone, regardless of age, body
+size, disability, ethnicity, gender identity and expression, level of experience,
+nationality, personal appearance, race, religion, or sexual identity and
+orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to creating a positive environment
+include:
+
+* Using welcoming and inclusive language
+* Being respectful of differing viewpoints and experiences
+* Gracefully accepting constructive criticism
+* Focusing on what is best for the community
+* Showing empathy towards other community members
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery and unwelcome sexual attention or
+advances
+* Trolling, insulting/derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or electronic
+  address, without explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Our Responsibilities
+
+Project maintainers are responsible for clarifying the standards of acceptable
+behavior and are expected to take appropriate and fair corrective action in
+response to any instances of unacceptable behavior.
+
+Project maintainers have the right and responsibility to remove, edit, or
+reject comments, commits, code, wiki edits, issues, and other contributions
+that are not aligned to this Code of Conduct, or to ban temporarily or
+permanently any contributor for other behaviors that they deem inappropriate,
+threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies both within project spaces and in public spaces
+when an individual is representing the project or its community. Examples of
+representing a project or community include using an official project e-mail
+address, posting via an official social media account, or acting as an appointed
+representative at an online or offline event. Representation of a project may be
+further defined and clarified by project maintainers.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by contacting the project team at m.tancoigne@gmail.com. All
+complaints will be reviewed and investigated and will result in a response that
+is deemed necessary and appropriate to the circumstances. The project team is
+obligated to maintain confidentiality with regard to the reporter of an incident.
+Further details of specific enforcement policies may be posted separately.
+
+Project maintainers who do not follow or enforce the Code of Conduct in good
+faith may face temporary or permanent repercussions as determined by other
+members of the project's leadership.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
+available at [http://contributor-covenant.org/version/1/4][version]
+
+[homepage]: http://contributor-covenant.org
+[version]: http://contributor-covenant.org/version/1/4/

data/Gemfile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+git_source(:github) { |repo_name| "https://github.com/#{repo_name}" }
+
+# Specify your gem's dependencies in rspec-rails-api.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2019 Manuel Tancoigne
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,457 @@
+# RspecRailsApiDoc
+
+> An RSpec plugin to test Rails api responses and generate swagger
+> documentation
+
+**This is a work in progress** but you're welcome to help, test, submit
+issues, ...
+
+## Installation
+
+As the gem is not yet published, you have to specify its git repository
+in order to test it.
+
+Add this line to your application's Gemfile:
+
+```rb
+gem 'rspec-rails-api'
+```
+
+And then execute:
+
+```sh
+bundle
+```
+
+### Rails configuration
+
+Configuration should be made manually for now:
+
+**spec/acceptance_helper.rb**
+
+```rb
+require 'rails_helper'
+require 'rspec_rails_api'
+
+RSpec.configure do |config|
+  config.include Rspec::Rails::Api::DSL::Example
+end
+
+renderer = Rspec::Rails::Api::OpenApiRenderer.new
+
+RSpec.configuration.after(:context, type: :acceptance) do |context|
+  renderer.merge_context context.class.metadata[:rrad].to_h
+end
+
+RSpec.configuration.after(:suite) do
+  renderer.write_files
+end
+```
+
+**spec/rails_helper.rb**
+
+```rb
+# ...
+
+RSpec::Rails::DIRECTORY_MAPPINGS[:acceptance] = %w[spec acceptance]
+
+RSpec.configure do |config|
+  # ...
+  config.include RSpec::Rails::RequestExampleGroup, :type => :acceptance
+end
+```
+
+## Configuration
+
+TODO
+
+## Usage
+
+Write some spec files and run RSpec as you would usually do.
+
+If you want to generate the documentation without testing the endpoints
+(and thus, without examples in generated files), use the `DOC_ONLY`
+environment variable:
+
+```rb
+DOC_ONLY=true bundle exec rails spec
+```
+
+For now, files are saved as `tmp/out.json` and `tmp/out.yml`.
+
+There is nothing to customize the file headers (info, license, ...) yet.
+
+## Writing specs
+
+There is a [commented example](examples/commented.rb) available in
+`doc/`.
+
+The idea is to have a simple DSL, and declare things like:
+
+**spec/acceptance/users_spec.rb**
+
+```rb
+require 'acceptance_helper'
+
+RSpec.describe 'Users', type: :acceptance do
+  resource 'Users', 'Manage users'
+
+  entity :user,
+         id:         { type: :integer, description: 'The id' },
+         email:      { type: :string, description: 'The name' },
+         role:       { type: :string, description: 'The name' },
+         created_at: { type: :datetime, description: 'Creation date' },
+         updated_at: { type: :datetime, description: 'Modification date' },
+         url:        { type: :string, description: 'URL to this category' }
+
+  on_get '/api/users/', 'Users list' do
+    for_code 200, 'Success response' do |example|
+      visit example
+      expect(response).to have_many defined :user
+    end
+  end
+
+  on_put '/api/users/:id', 'Users list' do
+    path_param id: { type: :integer, description: 'User Id' }
+
+    request_params user: {
+      type: :object, required: true, properties: {
+        name:  { type: :string, required: false, description: 'New name' },
+        email: { type: :string, required: false, description: 'New email' },
+        role:  { type: :string, required: false, description: 'New role' },
+      }
+    }
+
+    for_code 200, 'Success response' do |example|
+      visit example
+      expect(response).to have_one defined :user
+    end
+  end
+end
+```
+
+### DSL
+
+#### Example groups
+
+##### `resource(name, description)`
+
+Starts a resource description.
+
+- It must be called before any other documentation calls.
+- It should be in the first `describe block`
+
+##### `entity(name, fields)`
+
+Describes an entity for the documentation. The name is not visible, so
+you can put whatever fits (i.e: `:account`, `:user` if the content
+differs)
+
+They are ideally in the main `describe` block.
+
+- `name` is a symbol
+- `description` is a hash of attributes
+
+```rb
+{
+  id: { type: :integer, desc: 'The resource identifier' },
+  name: { type: :string, desc: 'The resource name' },
+  # ...
+}
+```
+
+An attribute should have the following form:
+
+```
+<field_name>: {type: <type>, desc: <description>}
+```
+
+- `type` can be any of the accepted
+  [OpenAPI types](http://spec.openapis.org/oas/v3.0.2#dataTypeFormat):
+  - `:integer`, `:int32`, `:int64`
+  - `:number`, `:float`, `:double`
+  - `:string`, `:byte`, `:binary`
+  - `:boolean`
+  - `:date`, `:datetime`
+  - `:password`
+  - `:object`, `:array`
+
+- `description` should be some valid
+  [CommonMark](https://commonmark.org/)
+
+###### Objects and arrays
+
+To describe complex structures, use `:object` with `:attributes` and
+`:array` `:of` something:
+
+```rb
+entity :friend,
+       name:    { type: :string, required: false, description: 'Friend name' }
+
+entity :user,
+       id:      { type: :number, required: false, description: 'Identifier' },
+       name:    { type: :string, required: false, description: 'The name' },
+       friends: { type: :array, of: :friend, required: false, description: 'Friends list'},
+       dog:     { type: :object, required: false, description: 'The dog', attributes: :dog },
+       cat:     {
+         type: :object, required: false, description: 'The cat', attributes: {
+           name: { type: :string, required: false, description: 'Cat name' },
+         }
+       }
+```
+
+In this example, there is an `:array, of: :friend`, which is a reference
+to the `:friend` entity described above; an `:object` with `:dog`
+attributes (reference too); and a cat object with its attributes defined
+inline.
+
+Both `:of` and `attributes` may be a hash of fields or a symbol. If they
+are omitted, they will be documented, but responses won't be validated.
+
+##### `on_<xxx>(url, description, &block)`
+
+Defines an URL.
+
+- `url` should be a relative URL to an existing endpoint (i.e.:
+  `/api/users`)
+- `description` should be some valid
+  [CommonMark](https://commonmark.org/)
+
+For now, only these methods are available:
+
+- `on_get`
+- `on_post`
+- `on_put`
+- `on_patch`
+- `on_delete`
+
+##### `path_params(<hash_of_attributes>)`
+
+Defines the path parameters that are used in the URL.
+
+```rb
+on_get '/api/users/:id/posts/:post_slug?full=:full_post' do
+  path_params id:        type: :integer, description: 'The user ID',
+              post_slug: type: :string, description: 'The post slug',
+              full_post: type: :boolean, required: false, description: 'Returns the full post if `true`, or only an excerpt',
+
+  # ...
+end
+```
+
+- `type` is the field type (check _entity definition_ for a list).
+- `description` should be some valid
+  [CommonMark](https://commonmark.org/)
+- `required` is optional an defaults to `true`.
+
+##### `request_params(<hash_of_attributes>)`
+
+Defines the format of the JSON payload. Type `object` is supported, so
+nested elements can be described:
+
+```rb
+on_post '/api/items' do
+  request_params item: { type: :object, required: true, properties: {
+                         name: { type: integer, description: 'The name of the new item', required: true },
+                         notes: { type: string, description: 'Additional notes' }
+                         },
+                       }
+  #...
+end
+```
+
+An attribute should have the following form:
+
+```
+<attr_name>: {type: <type>, desc: <description>, required: <required>, properties: <another_hash> }
+```
+
+- `attr_name` is the attribute name (sic)
+- `type` is the field type (check _entity definition_ for a list).
+  `type` can be `:object` if the attribute contains other attributes.
+- `required` is optional an defaults to `false`.
+- `properties` is a hash of params and is only used if `type: :object`
+
+##### `for_code(http_status, description, doc_only: false &block)`
+
+Describes the desired output for a precedently defined URL.
+
+Block takes one required argument, that should be passed to `visit`.
+This argument will contain the block context and allow `visit` to access
+the metadatas.
+
+- `http_status` is an integer representing an
+  [HTTP status](https://httpstat.us/)
+- `description` should be some valid
+  [CommonMark](https://commonmark.org/)
+- `doc_only` can be set to true to temporarily disable block execution
+  and only create the documentation (without examples).
+- `block` where additional tests can be performed. If `visit()` is
+  called within the block, its output will be used in documentation
+  examples, and the response type and code will actually be tested.
+
+If no block is passed, only the documentation will be generated, without
+examples. This can be useful to document endpoints that are impossible
+to test.
+
+Once again, you have to pass an argument to the block if you use
+`visit`.
+
+```rb
+# ...
+  for_code 200 'A successful response' do |example|
+    visit example
+    # ...
+  end
+# ...
+```
+
+#### Examples
+
+Example methods are available in `for_code` blocks
+
+##### `visit(example, path_params: {}, payload: {})`
+
+Visits the described URL and:
+
+- Expects the response code to match the described one
+- Expects the content type to be `application/json`
+
+- `example` is required and should be the block context (yep, i'll never
+  say it enough)
+- `path_params`: a hash of overrides for path params (useful if a custom
+  value is needed)
+- `payload`: a hash of values to send. Ignored for GET and DELETE
+  requests
+
+```rb
+for_code 200, 'Success' do |example|
+  visit example
+end
+```
+
+#### Matchers
+
+##### `have_one(type)`
+
+Expects the compared content to be a hash with the same keys as a
+defined entity.
+
+It should be compared against a hash or a `response` object:
+
+```rb
+#...
+entity user:
+       id:   { type: :integer, desc: 'The id',
+       name: { type: :string, desc: 'The name'
+
+#...
+
+expect({name: 'John'}).to have_one defined :user # Fails because `id` is missing
+
+# OR
+expect(response).to have_one defined :user
+```
+
+`defined` will get the correct entity.
+
+##### `have_many(type)`
+
+Expects the compared content to be an array of hashes with the same keys
+as a defined entity.
+
+It should be compared against an array or a `response` object:
+
+```rb
+#...
+entity user:
+       id:   { type: :integer, desc: 'The id',
+       name: { type: :string, desc: 'The name'
+
+#...
+
+expect([{id: 2, name: 'Jessica'}, {name: 'John'}]).to have_many defined :user # Fails because `id` is missing in the second entry
+
+# OR
+expect(response).to have_many defined :user
+```
+
+`defined` will get the correct entity.
+
+## Limitations
+
+### Contexts
+
+Contexts will break the thing. This is due to how the gem builds its
+metadata, relying on the parents metadata. You have to stick to the DSL.
+
+```rb
+RSpec.describe 'Categories', type: :request do
+  describe 'Categories'
+
+  context 'Authenticated' do
+    on_get '/api/categories', 'List all categories' do
+      # ...
+    end
+  end
+
+  # or
+
+  on_get '/api/categories', 'List all categories' do
+    context 'Authenticated' do
+      # ...
+    end
+  end
+
+  # won't work as expected.
+end
+```
+
+MRs to change this are welcome.
+
+### Request parameters
+
+Arrays of objects are not supported yet (i.e.: to describe nested
+attributes of an `has_many` relation)
+
+MRs to improve this are welcome.
+
+### Headers
+
+There is no way to have custom headers yet. This means, no token-based
+auth.
+
+### Files
+
+There is no support for file fields yet.
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies.
+Then, run `rake spec` to run the tests. You can also run `bin/console`
+for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake
+install`. To release a new version, update the version number in
+`version.rb`, and then run `bundle exec rake release`, which will create
+a git tag for the version, push git commits and tags, and push the
+`.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitLab at
+https://gitlab.com/experimentslabs/rspec-rails-api/issues. This
+project is intended to be a safe, welcoming space for collaboration, and
+contributors are expected to adhere to the
+[Contributor Covenant](http://contributor-covenant.org) code of conduct.
+
+## License
+
+The gem is available as open source under the terms of the
+[MIT License](https://opensource.org/licenses/MIT).
+
+## Code of Conduct
+
+Everyone interacting in the RspecRailsApiDoc project’s codebases, issue
+trackers, chat rooms and mailing lists is expected to follow the
+[code of conduct](https://gitlab.com/experimentslabs/rspec-rails-api/blob/master/CODE_OF_CONDUCT.md).