From e98b205ce764fb98f838ef3e8087ebbfa9c67ad6 Mon Sep 17 00:00:00 2001 From: Adrien Date: Wed, 13 Oct 2021 23:00:48 +0200 Subject: [PATCH] doc: give this api some chance with some swag --- Gemfile | 2 + Gemfile.lock | 4 ++ app/controllers/api/pokemons_controller.rb | 23 +++++++- config/initializers/swagger-docs.rb | 25 ++++++++ public/api-docs.json | 19 ++++++ public/api/pokemons.json | 67 ++++++++++++++++++++++ 6 files changed, 139 insertions(+), 1 deletion(-) create mode 100644 config/initializers/swagger-docs.rb create mode 100644 public/api-docs.json create mode 100644 public/api/pokemons.json diff --git a/Gemfile b/Gemfile index 1f9d575..dfbcd19 100644 --- a/Gemfile +++ b/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 diff --git a/Gemfile.lock b/Gemfile.lock index d5c653d..f0f7c7a 100644 --- a/Gemfile.lock +++ b/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) diff --git a/app/controllers/api/pokemons_controller.rb b/app/controllers/api/pokemons_controller.rb index 943aad9..f94fa19 100644 --- a/app/controllers/api/pokemons_controller.rb +++ b/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 diff --git a/config/initializers/swagger-docs.rb b/config/initializers/swagger-docs.rb new file mode 100644 index 0000000..4d95e0c --- /dev/null +++ b/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" => "adrien@sent.com", + "license" => "WTFPL", + "licenseUrl" => "http://www.wtfpl.net/txt/copying/" + } + } + } +}) diff --git a/public/api-docs.json b/public/api-docs.json new file mode 100644 index 0000000..a4e5b78 --- /dev/null +++ b/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": "adrien@sent.com", + "license": "WTFPL", + "licenseUrl": "http://www.wtfpl.net/txt/copying/" + } +} \ No newline at end of file diff --git a/public/api/pokemons.json b/public/api/pokemons.json new file mode 100644 index 0000000..724daa4 --- /dev/null +++ b/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 +} \ No newline at end of file