ditkrg/rswag
4
0
Fork 0
mirror of https://github.com/ditkrg/rswag.git synced 2026-01-22 22:06:43 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge remote-tracking branch 'olegkyz/bugfix/examples-content' into jamie

Browse Source
This commit is contained in:
Jamie Macey 2020-10-17 13:14:47 -07:00
commit 7e2c52b242
6 changed files with 47 additions and 33 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

42
README.md
View File

@ -363,8 +363,8 @@ you should use the folowing syntax, making sure there are no whitespaces at the
### Specifying/Testing API Security ### ### Specifying/Testing API Security ###
Swagger allows for the specification of different security schemes and their applicability to operations in an API. Swagger allows for the specification of different security schemes and their applicability to operations in an API.
To leverage this in rswag, you define the schemes globally in _swagger_helper.rb_ and then use the "security" attribute at the operation level to specify which schemes, if any, are applicable to that operation. To leverage this in rswag, you define the schemes globally in _swagger_helper.rb_ and then use the "security" attribute at the operation level to specify which schemes, if any, are applicable to that operation.
Swagger supports :basic, :bearer, :apiKey and :oauth2 and :openIdConnect scheme types. See [the spec](https://swagger.io/docs/specification/authentication/) for more info, as this underwent major changes between Swagger 2.0 and Open API 3.0 Swagger supports :basic, :bearer, :apiKey and :oauth2 and :openIdConnect scheme types. See [the spec](https://swagger.io/docs/specification/authentication/) for more info, as this underwent major changes between Swagger 2.0 and Open API 3.0
```ruby ```ruby
@ -416,7 +416,7 @@ describe 'Blogs API' do
end end
# example of documenting an endpoint that handles basic auth and api key based security # example of documenting an endpoint that handles basic auth and api key based security
describe 'Auth examples API' do describe 'Auth examples API' do
path '/auth-tests/basic-and-api-key' do path '/auth-tests/basic-and-api-key' do
post 'Authenticates with basic auth and api key' do post 'Authenticates with basic auth and api key' do
tags 'Auth Tests' tags 'Auth Tests'
@ -437,11 +437,11 @@ describe 'Auth examples API' do
end end
end end
end end
``` ```
__NOTE:__ Depending on the scheme types, you'll be required to assign a corresponding parameter value with each example. __NOTE:__ Depending on the scheme types, you'll be required to assign a corresponding parameter value with each example.
For example, :basic auth is required above and so the :Authorization (header) parameter must be set accordingly For example, :basic auth is required above and so the :Authorization (header) parameter must be set accordingly
## Configuration & Customization ## ## Configuration & Customization ##
@ -479,9 +479,9 @@ rake rswag:specs:swaggerize PATTERN="spec/swagger/**/*_spec.rb"
### Referenced Parameters and Schema Definitions ### ### Referenced Parameters and Schema Definitions ###
Swagger allows you to describe JSON structures inline with your operation descriptions OR as referenced globals. Swagger allows you to describe JSON structures inline with your operation descriptions OR as referenced globals.
For example, you might have a standard response structure for all failed operations. For example, you might have a standard response structure for all failed operations.
Again, this is a structure that changed since swagger 2.0. Notice the new "schemas" section for these. Again, this is a structure that changed since swagger 2.0. Notice the new "schemas" section for these.
Rather than repeating the schema in every operation spec, you can define it globally and provide a reference to it in each spec: Rather than repeating the schema in every operation spec, you can define it globally and provide a reference to it in each spec:
```ruby ```ruby
@ -560,7 +560,7 @@ end
### Response headers ### ### Response headers ###
In Rswag, you could use `header` method inside the response block to specify header objects for this response. In Rswag, you could use `header` method inside the response block to specify header objects for this response.
Rswag will validate your response headers with those header objects and inject them into the generated swagger file: Rswag will validate your response headers with those header objects and inject them into the generated swagger file:
```ruby ```ruby
@ -608,16 +608,20 @@ To enable examples generation from responses add callback above run_test! like:
``` ```
after do |example| after do |example|
example.metadata[:response][:examples] = { 'application/json' => JSON.parse(response.body, symbolize_names: true) } example.metadata[:response][:content] = {
'application/json' => {
example: JSON.parse(response.body, symbolize_names: true)
}
}
end end
``` ```
You need to disable --dry-run option for Rspec > 3 You need to disable --dry-run option for Rspec > 3
<!-- This is now enabled by default in rswag. <!-- This is now enabled by default in rswag.
You need to set the ``` config.swagger_dry_run = false``` value in the spec/spec_helper.rb file. You need to set the ``` config.swagger_dry_run = false``` value in the spec/spec_helper.rb file.
This is one of the more powerful features of rswag. When rswag runs your integration test suite via ```bundle exec rspec```, it will capture the request and response bodies and output those values in the examples section. This is one of the more powerful features of rswag. When rswag runs your integration test suite via ```bundle exec rspec```, it will capture the request and response bodies and output those values in the examples section.
These integration tests are usually written with ```let``` variables for post body parameters, and since its an integration test the service is returning actual values. These integration tests are usually written with ```let``` variables for post body parameters, and since its an integration test the service is returning actual values.
We might as well re-use these values and embed them into the generated swagger to provide a more real world example for request/response examples. --> We might as well re-use these values and embed them into the generated swagger to provide a more real world example for request/response examples. -->
Add to config/environments/test.rb: Add to config/environments/test.rb:
@ -656,8 +660,8 @@ describe 'Blogs API', document: false do
``` ```
##### rswag helper methods ##### ##### rswag helper methods #####
<!-- <!--
There are some helper methods to help with documenting request bodies. There are some helper methods to help with documenting request bodies.
```ruby ```ruby
describe 'Blogs API', type: :request, swagger_doc: 'v1/swagger.json' do describe 'Blogs API', type: :request, swagger_doc: 'v1/swagger.json' do
let(:api_key) { 'fake_key' } let(:api_key) { 'fake_key' }
@ -693,7 +697,7 @@ describe 'Blogs API', type: :request, swagger_doc: 'v1/swagger.json' do
end end
end end
end end
end end
``` ```
In the above example, we see methods ```request_body_json``` ```request_body_plain``` ```request_body_xml```. In the above example, we see methods ```request_body_json``` ```request_body_plain``` ```request_body_xml```.
@ -703,7 +707,7 @@ and the examples: :blog which will create a named example "blog" under the "requ
Again, documenting request response examples changed in Open API 3.0. The example above would generate a swagger.json snippet that looks like this: Again, documenting request response examples changed in Open API 3.0. The example above would generate a swagger.json snippet that looks like this:
```json ```json
... ...
{"requestBody": { {"requestBody": {
"required": true, "required": true,
"content": { "content": {
@ -737,9 +741,9 @@ Again, documenting request response examples changed in Open API 3.0. The exampl
} }
``` ```
*NOTE:* for this example request body to work in the tests properly, you need to ``let`` a variable named *blog*. *NOTE:* for this example request body to work in the tests properly, you need to ``let`` a variable named *blog*.
The variable with the matching name (blog in this case) is eval-ed and captured to be placed in the examples section. The variable with the matching name (blog in this case) is eval-ed and captured to be placed in the examples section.
This ```let``` value is used in the integration test to run the test AND captured and injected into the requestBody section. This ```let``` value is used in the integration test to run the test AND captured and injected into the requestBody section.
##### rswag response examples ##### ##### rswag response examples #####
@ -837,7 +841,7 @@ You can specify custom headers for serving your generated Swagger JSON. For exam
```ruby ```ruby
Rswag::Api.configure do |c| Rswag::Api.configure do |c|
... ...
c.swagger_headers = { 'Content-Type' => 'application/json; charset=UTF-8' } c.swagger_headers = { 'Content-Type' => 'application/json; charset=UTF-8' }
end end
``` ```
@ -909,5 +913,5 @@ docker pull swaggerapi/swagger-editor
``` ```
docker run -d -p 80:8080 swaggerapi/swagger-editor docker run -d -p 80:8080 swaggerapi/swagger-editor
``` ```
This will run the swagger editor in the docker daemon and can be accessed This will run the swagger editor in the docker daemon and can be accessed
at ```http://localhost```. From here, you can use the UI to load the generated swagger.json to validate the output. at ```http://localhost```. From here, you can use the UI to load the generated swagger.json to validate the output.

6
rswag-specs/lib/generators/rspec/templates/spec.rb
View File

@ -19,7 +19,11 @@ RSpec.describe '<%= controller_path %>', type: :request do
<% end -%> <% end -%>
after do |example| after do |example|
example.metadata[:response][:examples] = { 'application/json' => JSON.parse(response.body, symbolize_names: true) } example.metadata[:response][:content] = {
'application/json' => {
example: JSON.parse(response.body, symbolize_names: true)
}
}
end end
run_test! run_test!
end end

5
rswag-specs/lib/rswag/specs/example_group_helpers.rb
View File

@ -72,7 +72,10 @@ module Rswag
def examples(example = nil) def examples(example = nil)
return super() if example.nil? return super() if example.nil?
metadata[:response][:examples] = example metadata[:response][:content] =
example.each_with_object({}) do |(mime, example_object), memo|
memo[mime] = { example: example_object }
end
end end
def run_test!(&block) def run_test!(&block)

4
rswag-specs/lib/rswag/specs/swagger_formatter.rb
View File

@ -129,13 +129,13 @@ module Rswag
end end
def upgrade_content!(mime_list, target_node) def upgrade_content!(mime_list, target_node)
target_node.merge!(content: {}) target_node[:content] ||= {}
schema = target_node[:schema] schema = target_node[:schema]
return if mime_list.empty? || schema.nil? return if mime_list.empty? || schema.nil?
mime_list.each do |mime_type| mime_list.each do |mime_type|
# TODO upgrade to have content-type specific schema # TODO upgrade to have content-type specific schema
target_node[:content][mime_type] = { schema: schema } (target_node[:content][mime_type] ||= {}).merge!(schema: schema)
end end
end end

9
rswag-specs/spec/rswag/specs/example_group_helpers_spec.rb
View File

@ -137,9 +137,10 @@ module Rswag
end end
describe '#examples(example)' do describe '#examples(example)' do
let(:mime) { 'application/json' }
let(:json_example) do let(:json_example) do
{ {
'application/json' => { mime => {
foo: 'bar' foo: 'bar'
} }
} }
@ -151,7 +152,11 @@ module Rswag
end end
it "adds to the 'response examples' metadata" do it "adds to the 'response examples' metadata" do
expect(api_metadata[:response][:examples]).to eq(json_example) expect(api_metadata[:response][:content]).to match(
mime => {
example: json_example[mime]
}
)
end end
end end
end end

14
test-app/swagger/v1/swagger.json
View File

@ -235,16 +235,14 @@
"type": "string" "type": "string"
} }
}, },
"examples": {
"application/json": {
"id": 1,
"title": "Hello world!",
"content": "Hello world and hello universe. Thank you all very much!!!",
"thumbnail": "thumbnail.png"
}
},
"content": { "content": {
"application/json": { "application/json": {
"example": {
"id": 1,
"title": "Hello world!",
"content": "Hello world and hello universe. Thank you all very much!!!",
"thumbnail": "thumbnail.png"
},
"schema": { "schema": {
"$ref": "#/definitions/blog" "$ref": "#/definitions/blog"
} }