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

Updated Readme.md:

Browse Source 
Added a section on markdown formatting and and clarified some descriptions of API versioning
This commit is contained in:
Tomasz Czernuszenko 2017-08-07 14:12:40 +01:00 committed by GitHub
parent d91601b02c
commit 3eda72155a
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

@ -174,7 +174,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'
},
@ -183,7 +184,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'
}
@ -191,7 +193,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
@ -205,6 +208,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.