doc: give this api some chance with some swag

Gemfile

@@ -9,8 +9,10 @@ gem 'puma', '~> 5.0'
 gem 'sass-rails', '>= 6'
 gem 'jbuilder', '~> 2.7'
 gem 'bootsnap', '>= 1.4.4', require: false
+
 gem 'active_model_serializers', '~> 0.10.0'
 gem 'sidekiq'
+gem 'swagger-docs'
 
 group :development, :test do
   # Call 'byebug' anywhere in the code to stop execution and get a debugger console

Gemfile.lock

@@ -190,6 +190,9 @@ GEM
       activesupport (>= 4.0)
       sprockets (>= 3.0.0)
     sqlite3 (1.4.2)
+    swagger-docs (0.2.9)
+      activesupport (>= 3)
+      rails (>= 3)
     thor (1.1.0)
     tilt (2.0.10)
     tzinfo (2.0.4)
@@ -236,6 +239,7 @@ DEPENDENCIES
   sidekiq
   spring
   sqlite3 (~> 1.4)
+  swagger-docs
   tzinfo-data
   vcr
   web-console (>= 4.1.0)

app/controllers/api/pokemons_controller.rb

@@ -1,9 +1,30 @@
 class Api::PokemonsController < ApplicationController
+
+  swagger_controller :pokemons, "Pokemons"
+
+  swagger_api :index do
+    summary "To list pokemons"
+    response :success
+    response 500, "Internal Error"
+  end
   def index
     render json: Pokemon.preload(:pokemon_types, :types).all, include: ['types']
   end
 
+  swagger_api :show do
+    summary "To view the detail of a pokemon"
+    param :id, :integer, :required, "ID of the pokemon"
+    response :success
+    response :not_found
+    response 500, "Internal Error"
+  end
   def show
-    render json: Pokemon.find(params[:id]), include: ['types']
+    begin
+      pokemon = Pokemon.find(params[:id])
+
+      render json: pokemon, include: ['types']
+    rescue
+      render json: :not_found, status: :not_found
+    end
   end
 end

config/initializers/swagger-docs.rb

@@ -0,0 +1,25 @@
+Swagger::Docs::Config.register_apis({
+  "1.0" => {
+    # location where our api doc files will be generated, as of now we will store files under public directory
+    :api_file_path => "public/",
+    # base path url of our application
+    # while using production mode, point it to production url
+    :base_path => "http://localhost:3000",
+    # setting this option true tells swagger to clean all files generated in api_file_path directory before any files are generated
+    :clean_directory => true,
+    # As we are using Rails-API, our ApplicationController inherits ActionController::API instead of ActionController::Base
+    # Hence, we need to add ActionController::API instead of default ActionController::Base
+    :base_api_controller => ActionController::API,
+    # parent_controller needs to be specified if API controllers are inheriting some other controller than ApplicationController
+    # :parent_controller => ApplicationController,
+    :attributes => {
+      :info => {
+        "title" => "Regate API Doc",
+        "description" => "Give this API some SWAG",
+        "contact" => "[email protected]",
+        "license" => "WTFPL",
+        "licenseUrl" => "http://www.wtfpl.net/txt/copying/"
+      }
+    }
+  }
+})

public/api-docs.json

@@ -0,0 +1,19 @@
+{
+  "apiVersion": "1.0",
+  "swaggerVersion": "1.2",
+  "basePath": "http://localhost:3000",
+  "apis": [
+    {
+      "path": "/api/pokemons.{format}",
+      "description": "Pokemons"
+    }
+  ],
+  "authorizations": null,
+  "info": {
+    "title": "Regate API Doc",
+    "description": "Give this API some SWAG",
+    "contact": "[email protected]",
+    "license": "WTFPL",
+    "licenseUrl": "http://www.wtfpl.net/txt/copying/"
+  }
+}

public/api/pokemons.json

@@ -0,0 +1,67 @@
+{
+  "apiVersion": "1.0",
+  "swaggerVersion": "1.2",
+  "basePath": "http://localhost:3000",
+  "resourcePath": "pokemons",
+  "apis": [
+    {
+      "path": "/api/pokemons",
+      "operations": [
+        {
+          "summary": "To list pokemons",
+          "responseMessages": [
+            {
+              "code": 200,
+              "responseModel": null,
+              "message": "Ok"
+            },
+            {
+              "code": 500,
+              "responseModel": null,
+              "message": "Internal Error"
+            }
+          ],
+          "nickname": "Api::Pokemons#index",
+          "method": "get"
+        }
+      ]
+    },
+    {
+      "path": "/api/pokemons/{id}",
+      "operations": [
+        {
+          "summary": "To view the detail of a pokemon",
+          "responseMessages": [
+            {
+              "code": 200,
+              "responseModel": null,
+              "message": "Ok"
+            },
+            {
+              "code": 404,
+              "responseModel": null,
+              "message": "Not Found"
+            },
+            {
+              "code": 500,
+              "responseModel": null,
+              "message": "Internal Error"
+            }
+          ],
+          "parameters": [
+            {
+              "paramType": "id",
+              "name": "integer",
+              "type": "required",
+              "description": null,
+              "required": false
+            }
+          ],
+          "nickname": "Api::Pokemons#show",
+          "method": "get"
+        }
+      ]
+    }
+  ],
+  "authorizations": null
+}