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 pull request #92 from seriousbee/add-section-on-formatting-to-RM

Browse Source 
Updated Readme.md:
This commit is contained in:
Richard Morris 2019-04-08 12:17:05 +01:00 committed by GitHub
commit 636cdcd8b3
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 25 additions and 3 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

28
README.md
View File

@ -202,7 +202,8 @@ RSpec.configure do |config|
swagger: '2.0', swagger: '2.0',
info: { info: {
title: 'API V1', title: 'API V1',
version: 'v1' version: 'v1',
description: 'This is the first version of my API'
}, },
basePath: '/api/v1' basePath: '/api/v1'
}, },
@ -211,7 +212,8 @@ RSpec.configure do |config|
swagger: '2.0', swagger: '2.0',
info: { info: {
title: 'API V2', title: 'API V2',
version: 'v2' version: 'v2',
description: 'This is the second version of my API'
}, },
basePath: '/api/v2' basePath: '/api/v2'
} }
@ -219,7 +221,8 @@ RSpec.configure do |config|
end end
``` ```
__NOTE__: By default, the paths, operations and responses defined in your spec files will be associated with the first Swagger document in _swagger_helper.rb_. If you're using multiple documents, you'll need to tag the individual specs with their target document name: #### Supporting multiple versions of API ####
By default, the paths, operations and responses defined in your spec files will be associated with the first Swagger document in _swagger_helper.rb_. If your API has multiple versions, you should be using separate documents to describe each of them. In order to assign a file with a given version of API, you'll need to add the ```swagger_doc``` tag to each spec specifying its target document name:
```ruby ```ruby
# spec/integration/v2/blogs_spec.rb # spec/integration/v2/blogs_spec.rb
@ -233,6 +236,25 @@ describe 'Blogs API', swagger_doc: 'v2/swagger.json' do
end end
``` ```
#### Formatting the description literals: ####
Swagger supports the Markdown syntax to format strings. This can be especially handy if you were to provide a long description of a given API version or endpoint. Use [this guide](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet) for reference.
__NOTE:__ There is one difference between the official Markdown syntax and Swagger interpretation, namely tables. To create a table like this:
| Column1 | Collumn2 |
| ------- | -------- |
| cell1 | cell2 |
you should use the folowing syntax, making sure there are no whitespaces at the start of any of the lines:
```

| Column1 | Collumn2 |
| ------- | -------- |
| cell1 | cell2 |

```
### 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. 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, :apiKey and :oauth2 scheme types. See [the spec](http://swagger.io/specification/#security-definitions-object-109) for more info. 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. Swagger supports :basic, :apiKey and :oauth2 scheme types. See [the spec](http://swagger.io/specification/#security-definitions-object-109) for more info.