Adding description (Implementation Notes) for HTTP operations

.gitignore

@@ -13,3 +13,4 @@ bower_components/*
 bower_components/swagger-ui/*
 !bower_components/swagger-ui/dist
 .ruby-version
+.idea

Gemfile

@@ -19,3 +19,7 @@ group :development, :test do
   gem 'pry'
   gem 'generator_spec'
 end
+
+group :test do
+  gem 'test-unit'
+end

Gemfile.lock

@@ -1,9 +1,9 @@
 PATH
   remote: .
   specs:
-    swagger_rails (1.0.0.pre.beta2)
+    swagger_rails (1.0.0.pre.beta3)
       rack
-      rails (>= 3.1, < 5)
+      rails (>= 3.1, <= 5)
 
 GEM
   remote: https://rubygems.org/
@@ -54,6 +54,7 @@ GEM
     mime-types (1.25.1)
     multi_json (1.11.2)
     polyglot (0.3.5)
+    power_assert (0.2.6)
     pry (0.10.3)
       coderay (~> 1.1.0)
       method_source (~> 0.8.1)
@@ -107,12 +108,14 @@ GEM
       rack (~> 1.0)
       tilt (~> 1.1, != 1.3.0)
     sqlite3 (1.3.11)
+    test-unit (3.1.5)
+      power_assert
     thor (0.19.1)
     tilt (1.4.1)
     treetop (1.4.15)
       polyglot
       polyglot (>= 0.3.1)
-    tzinfo (0.3.50)
+    tzinfo (0.3.51)
 
 PLATFORMS
   ruby
@@ -123,6 +126,7 @@ DEPENDENCIES
   rspec-rails (~> 3.0)
   sqlite3
   swagger_rails!
+  test-unit
 
 BUNDLED WITH
-   1.10.6
+   1.12.5

Rakefile

@@ -1,3 +1,5 @@
+require 'rails'
+
 begin
   require 'bundler/setup'
 rescue LoadError

lib/swagger_rails/rspec/dsl.rb

@@ -20,6 +20,10 @@ module SwaggerRails
         describe(http_verb, metadata, &block)
       end
 
+      def operation_description(message)
+        metadata[:operation_description] = message
+      end
+
       [ :get, :post, :patch, :put, :delete, :head ].each do |http_verb|
         define_method(http_verb) do |summary=nil, &block|
           operation(http_verb, summary, &block)

lib/swagger_rails/rspec/formatter.rb

@@ -53,6 +53,7 @@ module SwaggerRails
         {
           tags: [ find_root_of(metadata)[:description] ] ,
           summary: metadata[:summary],
+          description: metadata[:operation_description],
           consumes: metadata[:consumes],
           produces: metadata[:produces],
           parameters: metadata[:parameters],

spec/dummy/spec/integration/blogs_spec.rb

@@ -7,6 +7,7 @@ describe 'Blogs API', swagger_doc: 'v1/swagger.json' do
     post 'creates a new blog' do
       consumes 'application/json'
       produces 'application/json'
+      operation_description 'Creates a new blog. You can provide detailed description here which will show up in Implementation Notes.'
       parameter :blog, :in => :body, schema: {
         :type => :object,
         :properties => {
@@ -36,7 +37,7 @@ describe 'Blogs API', swagger_doc: 'v1/swagger.json' do
   end
 
   path '/blogs/{id}' do
-    get 'retreives a specific blog' do
+    get 'retrieves a specific blog' do
       produces 'application/json'
       parameter :id, :in => :path, :type => :string