Skip to content

Commit b62517d

Browse files
ahxahx
committed
Update readme. Trying to make is simpler
1 parent 48c09e3 commit b62517d

1 file changed

Lines changed: 78 additions & 80 deletions

File tree

‎README.md‎

Lines changed: 78 additions & 80 deletions
Original file line numberDiff line numberDiff line change
@@ -4,36 +4,34 @@ openapi_first is a Ruby gem for request / response validation and contract-testi
44

55
## Usage
66

7-
Use an OAD to validate incoming requests in production:
7+
Use an OAD to validate incoming requests:
88
```ruby
99
use OpenapiFirst::Middlewares::RequestValidation, 'openapi/openapi.yaml'
1010
```
1111

12-
Turn your request tests into contract tests against an OAD:
12+
Turn your request tests into [contract tests](#contract-testing) against an OAD:
1313
```ruby
1414
# spec_helper.rb
1515
require 'openapi_first'
1616
OpenapiFirst::Test.setup do |config|
1717
config.register('openapi/openapi.yaml')
1818
end
1919

20-
require 'application' # Load Application code after calling OpenapiFirst::Test.setup.
20+
require 'my_app'
2121
RSpec.configure do |config|
2222
config.include OpenapiFirst::Test::Methods[MyApp], type: :request
2323
end
2424
```
2525

26-
Or use `OpenapiFirst::Test.app(MyApp)` to observe your app during tests. See [Contract testing](#contract-testing) for details.
27-
2826
## Contents
2927

3028
<!-- TOC -->
3129

32-
- [Contract testing](#contract-testing)
3330
- [Rack Middlewares](#rack-middlewares)
3431
- [Request validation](#request-validation)
3532
- [Response validation](#response-validation)
36-
- [Test assertions](#test-assertions)
33+
- [Contract testing](#contract-testing)
34+
- [Test assertions](#test-assertions)
3735
- [Manual use](#manual-use)
3836
- [Framework integration](#framework-integration)
3937
- [Configuration](#configuration)
@@ -46,78 +44,6 @@ Or use `OpenapiFirst::Test.app(MyApp)` to observe your app during tests. See [Co
4644

4745
<!-- /TOC -->
4846

49-
## Contract Testing
50-
51-
You can see your OpenAPI API description as a contract that your clients can rely on as how your API behaves. There are two aspects of contract testing: Validation and Coverage. By validating requests and responses, you can avoid that your API implementation processes requests or returns responses that don't match your API description. To make sure your _whole_ API description is implemented, openapi_first can check that all of your API description is covered when you test your API with [rack-test](https://github.com/rack/rack-test).
52-
53-
Here is how to set it up:
54-
55-
1. Register all OpenAPI documents to track coverage for.
56-
This should go at the top of your test helper file before loading your application code.
57-
```ruby
58-
require 'openapi_first'
59-
OpenapiFirst::Test.setup do |config|
60-
config.register('openapi/openapi.yaml')
61-
end
62-
```
63-
2. Observe your application. You can do this in multiple ways:
64-
- Add an `app` method to your tests, which wraps your application with silent request / response validation. (✷1)
65-
```ruby
66-
module RequestSpecHelpers
67-
def app
68-
OpenapiFirst::Test.app(MyApp)
69-
end
70-
end
71-
72-
RSpec.configure do |config|
73-
config.include RequestSpecHelpers, type: :request
74-
end
75-
```
76-
77-
Or do this by creating a Module and including it to add an "app" method.
78-
79-
```ruby
80-
RSpec.configure do |config|
81-
config.include OpenapiFirst::Test::Methods[MyApp], type: :request
82-
end
83-
```
84-
4. Run your tests. The Coverage feature will tell you about missing or invalid requests/responses.
85-
86-
(✷1): It does not matter what method of openapi_first you use to validate requests/responses. Instead of using `OpenapiFirstTest.app` to wrap your application, you could also use the [middlewares](#rack-middlewares) or [test assertion method](#test-assertions), but you would have to do that for all requests/responses defined in your API description to make coverage work.
87-
88-
### Configure test coverage
89-
90-
OpenapiFirst::Test raises an error when a request is not defined. You can deactivate this with:
91-
92-
```ruby
93-
OpenapiFirst::Test.setup do |test|
94-
# …
95-
test.ignore_unknown_requests = true
96-
end
97-
```
98-
99-
Exclude certain _responses_ from coverage with `skip_coverage`:
100-
101-
```ruby
102-
OpenapiFirst::Test.setup do |test|
103-
# …
104-
test.skip_response_coverage do |response_definition|
105-
response_definition.status == '5XX'
106-
end
107-
end
108-
```
109-
110-
Skip coverage for a request and all responses alltogether of a route with `skip_coverage`:
111-
112-
```ruby
113-
OpenapiFirst::Test.setup do |test|
114-
# …
115-
test.skip_coverage do |path, request_method|
116-
path == '/bookings/{bookingId}' && requests_method == 'DELETE'
117-
end
118-
end
119-
```
120-
12147
## Rack Middlewares
12248

12349
### Request validation
@@ -227,7 +153,79 @@ use OpenapiFirst::Middlewares::ResponseValidation, 'openapi.yaml', raise_error:
227153

228154
If you are adopting OpenAPI you can use these options together with [hooks](#hooks) to get notified about requests/responses that do match your API description.
229155

230-
## Test assertions
156+
## Contract Testing
157+
158+
You can see your OpenAPI API description as a contract that your clients can rely on as how your API behaves. There are two aspects of contract testing: Validation and Coverage. By validating requests and responses, you can avoid that your API implementation processes requests or returns responses that don't match your API description. To make sure your _whole_ API description is implemented, openapi_first can check that all of your API description is covered when you test your API with [rack-test](https://github.com/rack/rack-test).
159+
160+
Here is how to set it up:
161+
162+
1. Register all OpenAPI documents to track coverage for.
163+
This should go at the top of your test helper file before loading your application code.
164+
```ruby
165+
require 'openapi_first'
166+
OpenapiFirst::Test.setup do |config|
167+
config.register('openapi/openapi.yaml')
168+
end
169+
```
170+
2. Observe your application. You can do this in multiple ways:
171+
- Add an `app` method to your tests, which wraps your application with silent request / response validation. (✷1)
172+
```ruby
173+
module RequestSpecHelpers
174+
def app
175+
OpenapiFirst::Test.app(MyApp)
176+
end
177+
end
178+
179+
RSpec.configure do |config|
180+
config.include RequestSpecHelpers, type: :request
181+
end
182+
```
183+
184+
Or do this by creating a Module and including it to add an "app" method.
185+
186+
```ruby
187+
RSpec.configure do |config|
188+
config.include OpenapiFirst::Test::Methods[MyApp], type: :request
189+
end
190+
```
191+
4. Run your tests. The Coverage feature will tell you about missing or invalid requests/responses.
192+
193+
(✷1): It does not matter what method of openapi_first you use to validate requests/responses. Instead of using `OpenapiFirstTest.app` to wrap your application, you could also use the [middlewares](#rack-middlewares) or [test assertion method](#test-assertions), but you would have to do that for all requests/responses defined in your API description to make coverage work.
194+
195+
### Configure test coverage
196+
197+
OpenapiFirst::Test raises an error when a request is not defined. You can deactivate this with:
198+
199+
```ruby
200+
OpenapiFirst::Test.setup do |test|
201+
# …
202+
test.ignore_unknown_requests = true
203+
end
204+
```
205+
206+
Exclude certain _responses_ from coverage with `skip_coverage`:
207+
208+
```ruby
209+
OpenapiFirst::Test.setup do |test|
210+
# …
211+
test.skip_response_coverage do |response_definition|
212+
response_definition.status == '5XX'
213+
end
214+
end
215+
```
216+
217+
Skip coverage for a request and all responses alltogether of a route with `skip_coverage`:
218+
219+
```ruby
220+
OpenapiFirst::Test.setup do |test|
221+
# …
222+
test.skip_coverage do |path, request_method|
223+
path == '/bookings/{bookingId}' && requests_method == 'DELETE'
224+
end
225+
end
226+
```
227+
228+
### Test assertions
231229

232230
openapi_first ships with a simple but powerful Test method to run request and response validation in your tests without using the middlewares. This is designed to be used with rack-test or Ruby on Rails integration tests or request specs.
233231

0 commit comments

Comments
 (0)