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',
info: {
title: 'API V1',
version: 'v1'
version: 'v1',
description: 'This is the first version of my API'
},
basePath: '/api/v1'
},
@ -211,7 +212,8 @@ RSpec.configure do |config|
swagger: '2.0',
info: {
title: 'API V2',
version: 'v2'
version: 'v2',
description: 'This is the second version of my API'
},
basePath: '/api/v2'
}
@ -219,7 +221,8 @@ RSpec.configure do |config|
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
# spec/integration/v2/blogs_spec.rb
@ -233,6 +236,25 @@ describe 'Blogs API', swagger_doc: 'v2/swagger.json' do
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 ###
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.