Adding more documentation to the dummy rails application

spec/dummy/app/controllers/blogs_controller.rb

@@ -16,7 +16,8 @@ class BlogsController < ApplicationController
 
   # GET /blogs/1
   def show
-    @blog = Blog.find(params[:id])
+    @blog = Blog.find_by_id(params[:id])
+    respond_with @blog, status: :not_found and return unless @blog
     respond_with @blog
   end
 end

spec/dummy/spec/integration/blogs_spec.rb

@@ -39,6 +39,7 @@ describe 'Blogs API', swagger_doc: 'v1/swagger.json' do
   path '/blogs/{id}' do
     get 'retrieves a specific blog' do
       produces 'application/json'
+      operation_description 'For the id passed in the path, it searches and retrieves a blog against that id. If blog not found it returns a 404'
       parameter :id, :in => :path, :type => :string
 
       response '200', 'blog found' do
@@ -46,6 +47,11 @@ describe 'Blogs API', swagger_doc: 'v1/swagger.json' do
         let(:id) { blog.id }
         run_test!
       end
+
+      response '404', 'blog not found' do
+        let(:id) { 'invalid' }
+        run_test!
+      end
     end
   end
 end

spec/dummy/swagger/v1/swagger.json

@@ -11,6 +11,7 @@
           "Blogs API"
         ],
         "summary": "creates a new blog",
+        "description": "Creates a new blog. You can provide detailed description here which will show up in Implementation Notes.",
         "consumes": [
           "application/json"
         ],
@@ -48,6 +49,7 @@
           "Blogs API"
         ],
         "summary": "searches existing blogs",
+        "description": null,
         "consumes": null,
         "produces": [
           "application/json"
@@ -67,7 +69,8 @@
         "tags": [
           "Blogs API"
         ],
-        "summary": "retreives a specific blog",
+        "summary": "retrieves a specific blog",
+        "description": "For the id passed in the path, it searches and retrieves a blog against that id. If blog not found it returns a 404",
         "consumes": null,
         "produces": [
           "application/json"
@@ -82,6 +85,9 @@
         "responses": {
           "200": {
             "description": "blog found"
+          },
+          "404": {
+            "description": "blog not found"
           }
         }
       }