From 3eda72155a368edd9273f46638a5824cc4666114 Mon Sep 17 00:00:00 2001 From: Tomasz Czernuszenko Date: Mon, 7 Aug 2017 14:12:40 +0100 Subject: [PATCH] Updated Readme.md: Added a section on markdown formatting and and clarified some descriptions of API versioning --- README.md | 28 +++++++++++++++++++++++++--- 1 file changed, 25 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 63ed64a..4c1dce4 100644 --- a/README.md +++ b/README.md @@ -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.