rspec-rails-api 0.4.0 → 0.6.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- checksums.yaml +4 -4
- data/.gitignore +0 -5
- data/.gitlab-ci.yml +1 -1
- data/.rubocop.yml +5 -1
- data/.ruby-version +1 -0
- data/CHANGELOG.md +119 -27
- data/Gemfile.lock +98 -0
- data/README.md +210 -7
- data/lib/rspec/rails/api/dsl/example.rb +36 -19
- data/lib/rspec/rails/api/dsl/example_group.rb +12 -2
- data/lib/rspec/rails/api/entity_config.rb +7 -10
- data/lib/rspec/rails/api/field_config.rb +6 -3
- data/lib/rspec/rails/api/matchers.rb +22 -27
- data/lib/rspec/rails/api/metadata.rb +71 -35
- data/lib/rspec/rails/api/open_api_renderer.rb +161 -45
- data/lib/rspec/rails/api/utils.rb +28 -129
- data/lib/rspec/rails/api/validator.rb +211 -0
- data/lib/rspec/rails/api/version.rb +1 -1
- data/lib/rspec_rails_api.rb +2 -5
- data/rspec-rails-api.gemspec +4 -1
- metadata +49 -5
checksums.yaml
CHANGED
@@ -1,7 +1,7 @@
|
|
1
1
|
---
|
2
2
|
SHA256:
|
3
|
-
metadata.gz:
|
4
|
-
data.tar.gz:
|
3
|
+
metadata.gz: aa6db3329e09e4356d205cf49f100e11132a3e8a8fcb681ef8ede5e22ba470dd
|
4
|
+
data.tar.gz: e25b15faecc41214f92bb089f8fc9e28702f9c5ad2072daf4014251d30f23291
|
5
5
|
SHA512:
|
6
|
-
metadata.gz:
|
7
|
-
data.tar.gz:
|
6
|
+
metadata.gz: 2c947cf296de131ece545c7a21ed093d79de1e1fd5f57af53c58985eab815c781ce4dcbba7f7269c679dbf8155d4eabf0ae5035caa70bbd88090650630ed8e11
|
7
|
+
data.tar.gz: b0c4d8bef1c715b0ea369b5f7a659e8fa69344735af2a7735a51a1cb755c3fc3b642597c47a133be9568c0361d8565725ed803d2b0dd530050d1e286795ee911
|
data/.gitignore
CHANGED
data/.gitlab-ci.yml
CHANGED
data/.rubocop.yml
CHANGED
@@ -1,9 +1,11 @@
|
|
1
1
|
---
|
2
2
|
require:
|
3
3
|
- rubocop-performance
|
4
|
+
- rubocop-rake
|
5
|
+
- rubocop-rspec
|
4
6
|
|
5
7
|
AllCops:
|
6
|
-
TargetRubyVersion: 2.
|
8
|
+
TargetRubyVersion: 2.7
|
7
9
|
Exclude:
|
8
10
|
- dummy/**/*
|
9
11
|
- vendor/bundle/**/*
|
@@ -33,3 +35,5 @@ Style/TrailingCommaInArrayLiteral:
|
|
33
35
|
Style/TrailingCommaInHashLiteral:
|
34
36
|
EnforcedStyleForMultiline: comma
|
35
37
|
|
38
|
+
RSpec/NestedGroups:
|
39
|
+
Max: 4
|
data/.ruby-version
ADDED
@@ -0,0 +1 @@
|
|
1
|
+
2.7.0
|
data/CHANGELOG.md
CHANGED
@@ -1,13 +1,74 @@
|
|
1
1
|
# Change Log
|
2
2
|
All notable changes to this project will be documented in this file.
|
3
3
|
|
4
|
-
|
4
|
+
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
|
5
|
+
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
6
|
+
|
7
|
+
<!--
|
8
|
+
Quick remainder of the possible sections:
|
9
|
+
-----------------------------------------
|
10
|
+
Added, for new features.
|
11
|
+
Changed, for changes in existing functionality.
|
12
|
+
Deprecated, for soon-to-be removed features.
|
13
|
+
Removed, for now removed features.
|
14
|
+
Fixed, for any bug fixes.
|
15
|
+
Security, in case of vulnerabilities.
|
16
|
+
Maintenance, in case of rework, dependencies change
|
17
|
+
-->
|
18
|
+
|
19
|
+
## [Unreleased]
|
20
|
+
|
21
|
+
## [0.6.0] - 2023-07-17
|
22
|
+
|
23
|
+
### Added
|
24
|
+
|
25
|
+
- Declaring the same resource multiple times is now possible
|
26
|
+
- Add a simple support for security schemes
|
27
|
+
- Add support for global entities declarations. Keep things DRYer :)
|
28
|
+
- `test_response_of`: add `ignore_content_type` flag to ignore response's content type
|
29
|
+
- `test_response_of`: add `ignore_response` flag to ignore tests on response
|
30
|
+
- Renderer: Add simple support for redactable content. It will replace content in responses by something else. For now,
|
31
|
+
sub-entities are not redacted.
|
32
|
+
- Support for `file` type. When declaring a field with the `file` type, it will change the request content-type to
|
33
|
+
`multipart/form-data` automatically.
|
34
|
+
|
35
|
+
### Changed
|
36
|
+
|
37
|
+
- Generated JSON files will always be prettified to ease changes reviews when they are versioned
|
38
|
+
- When an unexpected 422 error happens, also display its content in error message
|
39
|
+
- [BREAKING] It is now impossible to declare the same entity twice. To remediate, rename your declared entities and/or
|
40
|
+
use global declarations. Check [README](./README.md) for example.
|
41
|
+
- Renderer: Use response data as-is when it's not valid JSON
|
42
|
+
|
43
|
+
### Fixed
|
44
|
+
|
45
|
+
- Strip generated descriptions and summaries
|
46
|
+
- Primitives are no more referenced in schemas for "expect_one" types
|
47
|
+
- Compare type `:float` against `Numeric` class
|
48
|
+
- Entities: Raise error when using `:array` type with `attributes` property and `:object` type with `of` property
|
49
|
+
- Rendering of sub-references now use the correct reference
|
50
|
+
- Metadata: Add missing type on array parameters
|
51
|
+
- Don't transform parameters into JSON when making `get` requests
|
52
|
+
- Operation IDs don't use summaries for uniqueness
|
53
|
+
- Downcase response content type before comparison
|
54
|
+
- Type format is now added on request parameters if applicable
|
55
|
+
|
56
|
+
## [0.5.0] - 2023-01-02
|
57
|
+
|
58
|
+
### Changed
|
59
|
+
|
60
|
+
- Improved error messages
|
61
|
+
- Improved usage of primitive types: use `:string` instead of `:type_string`, and more generally, remove the `type_`
|
62
|
+
prefix
|
63
|
+
|
64
|
+
### Fixed
|
65
|
+
-
|
66
|
+
- Fixed an error when an object is defined with an attribute named `type`.
|
67
|
+
|
68
|
+
## [0.4.0] - 2021-12-19
|
69
|
+
|
70
|
+
### Added
|
5
71
|
|
6
|
-
- All parameters attributes are considered required unless specified
|
7
|
-
- Fix object `attributes` key in spec and documentation.
|
8
|
-
When defining object attributes, documentation and tests used `properties` key
|
9
|
-
while the code was waiting for an `attributes` key. The later makes more sense
|
10
|
-
so the spec and documentation were fixed.
|
11
72
|
- Check for arrays of primitives is now a thing:
|
12
73
|
```rb
|
13
74
|
# In entities, when attribute is an array of primitives
|
@@ -19,15 +80,19 @@ All notable changes to this project will be documented in this file.
|
|
19
80
|
#...
|
20
81
|
end
|
21
82
|
```
|
22
|
-
- RSpec metadata is now stored in `rra` instead of `rrad` (the gem's first name
|
23
|
-
was RSpec Rails API Doc at the time). Update RSpec configuration accordingly.
|
24
83
|
- OpenApi:
|
25
84
|
- Responses now includes the schema
|
26
85
|
- `on_xxx` methods second parameter is now used as summary instead of description.
|
27
86
|
Description can be defined on the third parameter.
|
87
|
+
|
88
|
+
### Changed
|
89
|
+
|
90
|
+
- All parameters attributes are considered required unless specified
|
91
|
+
- RSpec metadata is now stored in `rra` instead of `rrad` (the gem's first name
|
92
|
+
was RSpec Rails API Doc at the time). Update RSpec configuration accordingly.
|
28
93
|
- DSL changes:
|
29
94
|
- `visit` is renamed to `test_response_of`
|
30
|
-
- Support for `doc_only` is removed
|
95
|
+
- Support for `doc_only` is removed
|
31
96
|
- Response expectations _should_ now be declared with `for_code`, and should be
|
32
97
|
removed from example bodies:
|
33
98
|
```rb
|
@@ -43,44 +108,71 @@ All notable changes to this project will be documented in this file.
|
|
43
108
|
end
|
44
109
|
```
|
45
110
|
|
111
|
+
### Fixed
|
112
|
+
|
113
|
+
- Fix object `attributes` key in spec and documentation.
|
114
|
+
When defining object attributes, documentation and tests used `properties` key
|
115
|
+
while the code was waiting for an `attributes` key. The later makes more sense
|
116
|
+
so the spec and documentation were fixed.
|
117
|
+
|
118
|
+
## [0.3.4] - 2021-10-20
|
119
|
+
|
120
|
+
### Added
|
46
121
|
|
47
|
-
## 0.3.4 - 2021-10-20
|
48
122
|
- Add the "required" attribute in parameters
|
49
123
|
|
50
|
-
## 0.3.3 - 2021-06-02
|
124
|
+
## [0.3.3] - 2021-06-02
|
125
|
+
|
126
|
+
### Fixed
|
127
|
+
|
51
128
|
- Fix correct types on request parameters
|
52
129
|
|
53
|
-
## 0.3.2 - 2021-03-09
|
54
|
-
|
130
|
+
## [0.3.2] - 2021-03-09
|
131
|
+
|
132
|
+
### Changed
|
133
|
+
|
55
134
|
- Render examples results as YAML/JSON objects instead of text blocks.
|
56
135
|
|
57
|
-
|
136
|
+
### Fixed
|
137
|
+
|
138
|
+
- Fix YAML rendering (ruby objects were sometimes rendered in documentation)
|
139
|
+
|
140
|
+
## [0.3.1] - 2020-04-09
|
141
|
+
|
142
|
+
### Added
|
143
|
+
|
58
144
|
- Add support for "test only" examples, allowing to write examples without documentation.
|
59
145
|
|
60
|
-
## 0.3.0 - 2019-12-26
|
146
|
+
## [0.3.0] - 2019-12-26
|
61
147
|
|
62
148
|
### Changed
|
149
|
+
|
63
150
|
- Rails 6 support, deprecated methods from Rails 5 are not supported. Use version `0.2.3`
|
64
151
|
of this gem if your application is still on 5.
|
65
152
|
|
66
153
|
## 0.2.3 - 2019-12-04
|
67
154
|
|
68
|
-
###
|
155
|
+
### Added
|
69
156
|
|
70
157
|
- Generated Swagger file now use the payloads of POST/PATCH/PUT requests.
|
71
|
-
- Minimum Ruby version is now specified: Ruby 2.3.3.
|
72
158
|
|
73
|
-
|
159
|
+
### Changed
|
74
160
|
|
75
|
-
|
76
|
-
|
161
|
+
- Minimum Ruby version is now specified: Ruby 2.3.3.
|
162
|
+
|
163
|
+
## [0.2.2] - 2019-11-03
|
77
164
|
|
78
165
|
### Changed
|
79
166
|
|
80
167
|
- `for_code` method now have its `description` optional. If none is provided,
|
81
168
|
the description will be set from the status code.
|
82
169
|
|
83
|
-
## 0.2.
|
170
|
+
## [0.2.1] - 2019-11-03 [YANKED]
|
171
|
+
|
172
|
+
_Version 0.2.1 was released and yanked by mistake. Version 0.2.2 is the exact
|
173
|
+
same one, with a version bump_
|
174
|
+
|
175
|
+
## [0.2.0] - 2019-11-02
|
84
176
|
|
85
177
|
### Added
|
86
178
|
|
@@ -99,35 +191,35 @@ of the fixtures.
|
|
99
191
|
the existing calls accordingly. To use params defined with `parameters`, use the
|
100
192
|
`defined` option: `request_params defined: :common_form_params`
|
101
193
|
|
102
|
-
## 0.1.5 - 2019-10-31
|
194
|
+
## [0.1.5] - 2019-10-31
|
103
195
|
|
104
196
|
### Fixed
|
105
197
|
|
106
198
|
- Fixed issue with POST/PUT/DELETE requests with no `request_params`
|
107
199
|
- Improved documentation (integration with Devise, typos and mistakes)
|
108
200
|
|
109
|
-
## 0.1.4 - 2019-10-24
|
201
|
+
## [0.1.4] - 2019-10-24
|
110
202
|
|
111
203
|
### Added
|
112
204
|
|
113
205
|
- Added support for arrays of objects in request parameters
|
114
206
|
|
115
|
-
## 0.1.3 - 2019-10-23
|
207
|
+
## [0.1.3] - 2019-10-23
|
116
208
|
|
117
209
|
### Added
|
118
210
|
|
119
211
|
- Added ability to document API descriptions, servers, etc... from the RSpec helper files
|
120
212
|
|
121
|
-
## 0.1.2 - 2019-10-22
|
213
|
+
## [0.1.2] - 2019-10-22
|
122
214
|
|
123
215
|
### Added
|
124
216
|
|
125
217
|
- Added `item` property for arrays descriptions
|
126
218
|
|
127
|
-
## 0.1.1 - 2019-10-22
|
219
|
+
## [0.1.1] - 2019-10-22
|
128
220
|
|
129
221
|
- Added support for custom headers in request examples (useful for `visit` method)
|
130
222
|
|
131
|
-
## 0.1.0 - 2019-10-21
|
223
|
+
## [0.1.0] - 2019-10-21
|
132
224
|
|
133
225
|
Initial release
|
data/Gemfile.lock
ADDED
@@ -0,0 +1,98 @@
|
|
1
|
+
PATH
|
2
|
+
remote: .
|
3
|
+
specs:
|
4
|
+
rspec-rails-api (0.6.0)
|
5
|
+
|
6
|
+
GEM
|
7
|
+
remote: https://rubygems.org/
|
8
|
+
specs:
|
9
|
+
activesupport (6.1.7)
|
10
|
+
concurrent-ruby (~> 1.0, >= 1.0.2)
|
11
|
+
i18n (>= 1.6, < 2)
|
12
|
+
minitest (>= 5.1)
|
13
|
+
tzinfo (~> 2.0)
|
14
|
+
zeitwerk (~> 2.3)
|
15
|
+
ast (2.4.2)
|
16
|
+
byebug (11.1.3)
|
17
|
+
concurrent-ruby (1.1.10)
|
18
|
+
diff-lcs (1.5.0)
|
19
|
+
docile (1.4.0)
|
20
|
+
i18n (1.12.0)
|
21
|
+
concurrent-ruby (~> 1.0)
|
22
|
+
json (2.6.3)
|
23
|
+
minitest (5.16.3)
|
24
|
+
parallel (1.22.1)
|
25
|
+
parser (3.1.3.0)
|
26
|
+
ast (~> 2.4.1)
|
27
|
+
rack (3.0.3)
|
28
|
+
rainbow (3.1.1)
|
29
|
+
rake (10.5.0)
|
30
|
+
regexp_parser (2.6.1)
|
31
|
+
rexml (3.2.5)
|
32
|
+
rspec (3.12.0)
|
33
|
+
rspec-core (~> 3.12.0)
|
34
|
+
rspec-expectations (~> 3.12.0)
|
35
|
+
rspec-mocks (~> 3.12.0)
|
36
|
+
rspec-core (3.12.0)
|
37
|
+
rspec-support (~> 3.12.0)
|
38
|
+
rspec-expectations (3.12.1)
|
39
|
+
diff-lcs (>= 1.2.0, < 2.0)
|
40
|
+
rspec-support (~> 3.12.0)
|
41
|
+
rspec-mocks (3.12.1)
|
42
|
+
diff-lcs (>= 1.2.0, < 2.0)
|
43
|
+
rspec-support (~> 3.12.0)
|
44
|
+
rspec-support (3.12.0)
|
45
|
+
rubocop (1.41.1)
|
46
|
+
json (~> 2.3)
|
47
|
+
parallel (~> 1.10)
|
48
|
+
parser (>= 3.1.2.1)
|
49
|
+
rainbow (>= 2.2.2, < 4.0)
|
50
|
+
regexp_parser (>= 1.8, < 3.0)
|
51
|
+
rexml (>= 3.2.5, < 4.0)
|
52
|
+
rubocop-ast (>= 1.23.0, < 2.0)
|
53
|
+
ruby-progressbar (~> 1.7)
|
54
|
+
unicode-display_width (>= 1.4.0, < 3.0)
|
55
|
+
rubocop-ast (1.24.1)
|
56
|
+
parser (>= 3.1.1.0)
|
57
|
+
rubocop-performance (1.15.2)
|
58
|
+
rubocop (>= 1.7.0, < 2.0)
|
59
|
+
rubocop-ast (>= 0.4.0)
|
60
|
+
rubocop-rake (0.6.0)
|
61
|
+
rubocop (~> 1.0)
|
62
|
+
rubocop-rspec (2.16.0)
|
63
|
+
rubocop (~> 1.33)
|
64
|
+
ruby-progressbar (1.11.0)
|
65
|
+
simplecov (0.22.0)
|
66
|
+
docile (~> 1.1)
|
67
|
+
simplecov-html (~> 0.11)
|
68
|
+
simplecov_json_formatter (~> 0.1)
|
69
|
+
simplecov-html (0.12.3)
|
70
|
+
simplecov_json_formatter (0.1.4)
|
71
|
+
tzinfo (2.0.5)
|
72
|
+
concurrent-ruby (~> 1.0)
|
73
|
+
unicode-display_width (2.3.0)
|
74
|
+
webrick (1.7.0)
|
75
|
+
yard (0.9.28)
|
76
|
+
webrick (~> 1.7.0)
|
77
|
+
zeitwerk (2.6.6)
|
78
|
+
|
79
|
+
PLATFORMS
|
80
|
+
x86_64-linux
|
81
|
+
|
82
|
+
DEPENDENCIES
|
83
|
+
activesupport (~> 6.0)
|
84
|
+
bundler
|
85
|
+
byebug
|
86
|
+
rack
|
87
|
+
rake (~> 10.0)
|
88
|
+
rspec (~> 3.0)
|
89
|
+
rspec-rails-api!
|
90
|
+
rubocop
|
91
|
+
rubocop-performance
|
92
|
+
rubocop-rake
|
93
|
+
rubocop-rspec
|
94
|
+
simplecov
|
95
|
+
yard
|
96
|
+
|
97
|
+
BUNDLED WITH
|
98
|
+
2.4.1
|
data/README.md
CHANGED
@@ -72,7 +72,101 @@ end
|
|
72
72
|
|
73
73
|
## Configuration
|
74
74
|
|
75
|
-
**TODO: This section is incomplete and the gem has no generator yet
|
75
|
+
**TODO: This section is incomplete and the gem has no generator yet.**
|
76
|
+
|
77
|
+
Here is an example configuration:
|
78
|
+
|
79
|
+
```rb
|
80
|
+
# spec/rails_helper.rb
|
81
|
+
require 'spec/support/rspec_rails_api'
|
82
|
+
```
|
83
|
+
|
84
|
+
```rb
|
85
|
+
# spec/support/acceptance_entities.rb
|
86
|
+
|
87
|
+
# This file contains common object definitions
|
88
|
+
{
|
89
|
+
error: {
|
90
|
+
error: { type: :string, description: "Error message" }
|
91
|
+
},
|
92
|
+
form_error: {
|
93
|
+
title: { type: :array, required: false, description: "Title errors", of: :string }
|
94
|
+
},
|
95
|
+
}.each do |name, attributes|
|
96
|
+
RSpec::Rails::Api::Metadata.add_entity name, attributes
|
97
|
+
end
|
98
|
+
```
|
99
|
+
|
100
|
+
```rb
|
101
|
+
# spec/support/rspec_rails_api.rb
|
102
|
+
require 'rspec_rails_api'
|
103
|
+
require 'support/acceptance_entities'
|
104
|
+
|
105
|
+
# Include DSL in RSpec
|
106
|
+
RSpec.configure do |config|
|
107
|
+
config.include RSpec::Rails::Api::DSL::Example
|
108
|
+
end
|
109
|
+
|
110
|
+
# Initialize and configure the renderer
|
111
|
+
renderer = RSpec::Rails::Api::OpenApiRenderer.new
|
112
|
+
# Server URL for quick reference
|
113
|
+
server_url = 'https://example.com'
|
114
|
+
|
115
|
+
# Options here should be present for a valid OpenAPI file
|
116
|
+
renderer.api_title = 'MyProject API'
|
117
|
+
renderer.api_version = '1'
|
118
|
+
|
119
|
+
# Options below are optional
|
120
|
+
#
|
121
|
+
# API description. Markdown supported
|
122
|
+
# renderer.api_description = 'Manage data on MyProject'
|
123
|
+
#
|
124
|
+
# List of servers, to live-test the documentation
|
125
|
+
# renderer.api_servers = [{ url: server_url }, { url: 'http://localhost:3000' }]
|
126
|
+
#
|
127
|
+
# Link to the API terms of service, if any
|
128
|
+
# renderer.api_tos = 'http://example.com/tos.html'
|
129
|
+
#
|
130
|
+
# Contact information
|
131
|
+
# renderer.api_contact = { name: 'Admin', email: 'admin@example.com', url: 'http://example.com/contact' }
|
132
|
+
#
|
133
|
+
# API license information
|
134
|
+
# renderer.api_license = { name: 'Apache', url: 'https://opensource.org/licenses/Apache-2.0' }
|
135
|
+
#
|
136
|
+
# Possible security schemes
|
137
|
+
# renderer.add_security_scheme :pkce_code_grant, 'PKCE code grant',
|
138
|
+
# type: 'oauth2',
|
139
|
+
# flows: {
|
140
|
+
# implicit: {
|
141
|
+
# authorizationUrl: "#{server_url}/oauth/authorize",
|
142
|
+
# scopes: { read: 'will read data on your behalf', write: 'will write data on your behalf' }
|
143
|
+
# }
|
144
|
+
# }
|
145
|
+
# renderer.add_security_scheme :bearer, 'Bearer token',
|
146
|
+
# type: 'http',
|
147
|
+
# scheme: 'bearer'
|
148
|
+
#
|
149
|
+
# Declare keys whose values should be filtered in responses.
|
150
|
+
# renderer.redact_responses entity_name: { key: 'REDACTED' },
|
151
|
+
# other_entity: { other_key: ['REDACTED'] }
|
152
|
+
|
153
|
+
|
154
|
+
# We need to merge each context metadata so we can reference to them to build the final file
|
155
|
+
RSpec.configuration.after(:context, type: :acceptance) do |context|
|
156
|
+
renderer.merge_context context.class.metadata[:rra].to_h
|
157
|
+
# During development of rspec_rails_api, you may want to dump raw metadata to a file
|
158
|
+
renderer.merge_context context.class.metadata[:rra].to_h, dump_metadata: true
|
159
|
+
end
|
160
|
+
|
161
|
+
# Skip this block if you don't need the OpenAPI documentation file and only have your responses tested
|
162
|
+
RSpec.configuration.after(:suite) do
|
163
|
+
renderer.write_files Rails.root.join('public/swagger') # Write both YAML and prettified JSON files
|
164
|
+
# or
|
165
|
+
renderer.write_files Rails.root.join('public/swagger'), only: [:json] # Prettified JSON only
|
166
|
+
# or
|
167
|
+
renderer.write_files Rails.root.join('public/swagger'), only: [:yaml] # YAML only
|
168
|
+
end
|
169
|
+
```
|
76
170
|
|
77
171
|
### Integration with Devise
|
78
172
|
|
@@ -124,7 +218,7 @@ end
|
|
124
218
|
# In examples
|
125
219
|
#...
|
126
220
|
for_code 200, 'Success' do |url|
|
127
|
-
|
221
|
+
sign_in #...
|
128
222
|
test_response_of url
|
129
223
|
|
130
224
|
#...
|
@@ -149,7 +243,7 @@ The idea is to have a simple DSL, and declare things like:
|
|
149
243
|
**spec/acceptance/users_spec.rb**
|
150
244
|
|
151
245
|
```ruby
|
152
|
-
require '
|
246
|
+
require 'rails_helper'
|
153
247
|
|
154
248
|
RSpec.describe 'Users', type: :acceptance do
|
155
249
|
resource 'Users', 'Manage users'
|
@@ -186,6 +280,78 @@ RSpec.describe 'Users', type: :acceptance do
|
|
186
280
|
end
|
187
281
|
```
|
188
282
|
|
283
|
+
### Entity declarations
|
284
|
+
|
285
|
+
You can declare entities locally (in every spec files), but sometimes you will need to use/reference the same entity
|
286
|
+
in multiple spec files (e.g.: an error message). In that case, you can create _global_ entities in separate files, and they
|
287
|
+
will be picked-up when needed.
|
288
|
+
|
289
|
+
Example of a local entity:
|
290
|
+
|
291
|
+
```rb
|
292
|
+
# spec/acceptance/api/users_acceptance_spec.rb
|
293
|
+
require 'rails_helper'
|
294
|
+
|
295
|
+
RSpec.describe 'Users', type: :acceptance do
|
296
|
+
resource 'Users', 'Manage users'
|
297
|
+
|
298
|
+
# This is a local entity
|
299
|
+
entity :user,
|
300
|
+
id: { type: :integer, description: 'The id' },
|
301
|
+
email: { type: :string, description: 'The name' },
|
302
|
+
role: { type: :string, description: 'The name' },
|
303
|
+
created_at: { type: :datetime, description: 'Creation date' },
|
304
|
+
updated_at: { type: :datetime, description: 'Modification date' },
|
305
|
+
url: { type: :string, description: 'URL to this category' }
|
306
|
+
|
307
|
+
on_get '/api/users/', 'Users list' do
|
308
|
+
for_code 200, 'Success response', expect_many: :user do |url|
|
309
|
+
test_response_of url
|
310
|
+
end
|
311
|
+
end
|
312
|
+
|
313
|
+
#...
|
314
|
+
end
|
315
|
+
```
|
316
|
+
|
317
|
+
Defining global entities:
|
318
|
+
|
319
|
+
```rb
|
320
|
+
# spec/support/entities/user.rb
|
321
|
+
# This file should be required at some point in the "rails_helper" or "acceptance_helper"
|
322
|
+
|
323
|
+
require 'rspec/rails/api/metadata'
|
324
|
+
|
325
|
+
RSpec::Rails::Api::Metadata.add_entity :user,
|
326
|
+
id: { type: :integer, description: 'The id' },
|
327
|
+
email: { type: :string, description: 'The name' },
|
328
|
+
role: { type: :string, description: 'The name' },
|
329
|
+
created_at: { type: :datetime, description: 'Creation date' },
|
330
|
+
updated_at: { type: :datetime, description: 'Modification date' },
|
331
|
+
url: { type: :string, description: 'URL to this category' }
|
332
|
+
|
333
|
+
```
|
334
|
+
|
335
|
+
Organization of the global entities declaration is up to you.
|
336
|
+
|
337
|
+
```rb
|
338
|
+
# spec/acceptance/api/users_acceptance_spec.rb
|
339
|
+
require 'rails_helper'
|
340
|
+
|
341
|
+
RSpec.describe 'Users', type: :acceptance do
|
342
|
+
resource 'Users', 'Manage users'
|
343
|
+
|
344
|
+
on_get '/api/users/', 'Users list' do
|
345
|
+
# "user" will use the global user entity
|
346
|
+
for_code 200, 'Success response', expect_many: :user do |url|
|
347
|
+
test_response_of url
|
348
|
+
end
|
349
|
+
end
|
350
|
+
|
351
|
+
#...
|
352
|
+
end
|
353
|
+
```
|
354
|
+
|
189
355
|
### DSL
|
190
356
|
|
191
357
|
#### Example groups
|
@@ -197,6 +363,23 @@ Starts a resource description.
|
|
197
363
|
- It must be called before any other documentation calls.
|
198
364
|
- It should be in the first `describe block`
|
199
365
|
|
366
|
+
A resource may be completed across multiple spec files:
|
367
|
+
|
368
|
+
```rb
|
369
|
+
# an_acceptance_spec.rb
|
370
|
+
RSpec.describe 'Something', type: :acceptance do
|
371
|
+
resource 'User', 'Manage users'
|
372
|
+
end
|
373
|
+
|
374
|
+
# another_acceptance_spec.rb
|
375
|
+
RSpec.describe 'Something else', type: :acceptance do
|
376
|
+
resource 'User', 'Another description'
|
377
|
+
end
|
378
|
+
|
379
|
+
```
|
380
|
+
|
381
|
+
The first evaluated `resource` statement will be used as description; all the tests in both files will complete it.
|
382
|
+
|
200
383
|
##### `entity(type, fields)`
|
201
384
|
|
202
385
|
Describes an entity for the documentation. The type is only a reference,
|
@@ -263,12 +446,12 @@ inline.
|
|
263
446
|
Both `:of` and `attributes` may be a hash of fields or a symbol. If they
|
264
447
|
are omitted, they will be documented, but responses won't be validated.
|
265
448
|
|
266
|
-
Arrays of primitives are supported;
|
267
|
-
|
449
|
+
Arrays of primitives are supported; refer to the [documentation](https://swagger.io/specification/#data-types) for the
|
450
|
+
list. Usage:
|
268
451
|
|
269
452
|
```rb
|
270
453
|
entity :user,
|
271
|
-
|
454
|
+
favorite_numbers: { type: :array, of: :int32 }
|
272
455
|
```
|
273
456
|
|
274
457
|
Check `lib/rspec_rails_api.rb` for the full list.
|
@@ -423,11 +606,30 @@ Once again, you have to pass an argument to the block if you use
|
|
423
606
|
# ...
|
424
607
|
```
|
425
608
|
|
609
|
+
##### `requires_security(scheme_references)`
|
610
|
+
|
611
|
+
Specifies the valid security schemes to use for this request. Security schemes are declared at the renderer level
|
612
|
+
(see [the configuration example](#Configuration)).
|
613
|
+
|
614
|
+
```rb
|
615
|
+
# Given a previously :basic scheme
|
616
|
+
|
617
|
+
# ...
|
618
|
+
on_get '/some/path' do
|
619
|
+
require_security :basic, :implicit
|
620
|
+
|
621
|
+
for_code 200 do |url|
|
622
|
+
#...
|
623
|
+
end
|
624
|
+
end
|
625
|
+
# ...
|
626
|
+
```
|
627
|
+
|
426
628
|
#### Examples
|
427
629
|
|
428
630
|
Example methods are available in `for_code` blocks
|
429
631
|
|
430
|
-
##### `test_response_of(example, path_params: {}, payload: {}, headers: {})`
|
632
|
+
##### `test_response_of(example, path_params: {}, payload: {}, headers: {}, ignore_content_type: false)`
|
431
633
|
|
432
634
|
Visits the described URL and:
|
433
635
|
|
@@ -441,6 +643,7 @@ Visits the described URL and:
|
|
441
643
|
- `payload`: a hash of values to send. Ignored for GET and DELETE
|
442
644
|
requests
|
443
645
|
- `headers`: a hash of custom headers.
|
646
|
+
- `ignore_content_type`: whether to ignore response's content-type. By default, checks for a JSON response
|
444
647
|
|
445
648
|
```ruby
|
446
649
|
for_code 200, 'Success' do |url|
|