[AFA-7] Add documentation

.gitignore

@@ -33,4 +33,7 @@
 /config/master.key
 
 # Redis dump
-dump.rdb
+dump.rdb
+
+# Ignore test coverage report
+/coverage/

.overcommit.yml

@@ -0,0 +1,33 @@
+# Use this file to configure the Overcommit hooks you wish to use. This will
+# extend the default configuration defined in:
+# https://github.com/sds/overcommit/blob/master/config/default.yml
+#
+# At the topmost level of this YAML file is a key representing type of hook
+# being run (e.g. pre-commit, commit-msg, etc.). Within each type you can
+# customize each hook, such as whether to only run it on certain files (via
+# `include`), whether to only display output if it fails (via `quiet`), etc.
+#
+# For a complete list of hooks, see:
+# https://github.com/sds/overcommit/tree/master/lib/overcommit/hook
+#
+# For a complete list of options that you can use to customize hooks, see:
+# https://github.com/sds/overcommit#configuration
+#
+# Uncomment the following lines to make the configuration take effect.
+
+PreCommit:
+  TrailingWhitespace:
+    enabled: true
+    description: "Check for trailing whitespace"
+  StandardRB:
+    enabled: true
+    description: "Analyze lint code"
+    on_warn: fail
+    command: ["bundle", "exec", "standardrb"]
+  Swagger:
+    enabled: true
+    description: "Generate the Swagger JSON file"
+    on_warn: fail
+    env:
+      RAILS_ENV: test
+    command: ["bundle", "exec", "rails", "rswag"]

Gemfile

@@ -24,13 +24,22 @@ gem "dotenv-rails", "3.1.0", require: "dotenv/load", groups: %i[development test
 gem "auction_fun_core", "0.8.10"
 # gem "auction_fun_core", path: "../auction_fun_core", require: "auction_fun_core"
 
+# API documentation
+gem "rswag-api", "2.13.0"
+gem "rswag-ui", "2.13.0"
+
+# Git hooks
+gem "overcommit", "0.63.0"
+
 group :development, :test do
   gem "pry-rails", "0.3.9"
   gem "rspec-rails", "6.1.2"
+  gem "rswag-specs", "2.13.0"
   gem "standard", "1.35.1"
 end
 
 group :test do
   gem "database_cleaner-sequel", "2.0.2"
   gem "rom-factory", "0.12.0"
+  gem "simplecov", "0.22.0"
 end

Gemfile.lock

@@ -75,6 +75,8 @@ GEM
       minitest (>= 5.1)
       mutex_m
       tzinfo (~> 2.0)
+    addressable (2.8.6)
+      public_suffix (>= 2.0.2, < 6.0)
     ast (2.4.2)
     auction_fun_core (0.8.10)
       activesupport (= 7.1.3.2)
@@ -102,6 +104,7 @@ GEM
     bootsnap (1.18.3)
       msgpack (~> 1.2)
     builder (3.2.4)
+    childprocess (5.0.0)
     coderay (1.1.3)
     concurrent-ruby (1.2.3)
     connection_pool (2.4.1)
@@ -112,6 +115,7 @@ GEM
       sequel
     date (3.3.4)
     diff-lcs (1.5.1)
+    docile (1.4.0)
     dotenv (3.1.0)
     dotenv-rails (3.1.0)
       dotenv (= 3.1.0)
@@ -182,11 +186,14 @@ GEM
     ice_nine (0.11.2)
     idlemailer (2.2.0)
       mail (~> 2.0)
+    iniparse (1.5.0)
     io-console (0.7.2)
     irb (1.12.0)
       rdoc
       reline (>= 0.4.2)
     json (2.7.1)
+    json-schema (4.3.0)
+      addressable (>= 2.8)
     language_server-protocol (3.17.0.3)
     lint_roller (1.1.0)
     loofah (2.22.0)
@@ -227,6 +234,10 @@ GEM
       racc (~> 1.4)
     nokogiri (1.16.2-x86_64-linux)
       racc (~> 1.4)
+    overcommit (0.63.0)
+      childprocess (>= 0.6.3, < 6)
+      iniparse (~> 1.4)
+      rexml (~> 3.2)
     parallel (1.24.0)
     parser (3.3.0.5)
       ast (~> 2.4.1)
@@ -240,6 +251,7 @@ GEM
       pry (>= 0.10.4)
     psych (5.1.2)
       stringio
+    public_suffix (5.0.5)
     puma (6.4.2)
       nio4r (~> 2.0)
     racc (1.7.3)
@@ -341,6 +353,17 @@ GEM
       rspec-mocks (~> 3.13)
       rspec-support (~> 3.13)
     rspec-support (3.13.1)
+    rswag-api (2.13.0)
+      activesupport (>= 3.1, < 7.2)
+      railties (>= 3.1, < 7.2)
+    rswag-specs (2.13.0)
+      activesupport (>= 3.1, < 7.2)
+      json-schema (>= 2.2, < 5.0)
+      railties (>= 3.1, < 7.2)
+      rspec-core (>= 2.14)
+    rswag-ui (2.13.0)
+      actionpack (>= 3.1, < 7.2)
+      railties (>= 3.1, < 7.2)
     rubocop (1.62.1)
       json (~> 2.3)
       language_server-protocol (>= 3.17.0)
@@ -369,6 +392,12 @@ GEM
       concurrent-ruby (~> 1.0, >= 1.0.5)
       sidekiq (>= 7.0.0, < 8.0.0)
       thor (>= 1.0, < 3.0)
+    simplecov (0.22.0)
+      docile (~> 1.1)
+      simplecov-html (~> 0.11)
+      simplecov_json_formatter (~> 0.1)
+    simplecov-html (0.12.3)
+    simplecov_json_formatter (0.1.4)
     standard (1.35.1)
       language_server-protocol (~> 3.17.0.2)
       lint_roller (~> 1.0)
@@ -408,13 +437,18 @@ DEPENDENCIES
   bootsnap (= 1.18.3)
   database_cleaner-sequel (= 2.0.2)
   dotenv-rails (= 3.1.0)
+  overcommit (= 0.63.0)
   pg (= 1.5.6)
   pry-rails (= 0.3.9)
   puma (= 6.4.2)
   rack-cors (= 2.0.2)
   rails (= 7.1.3.2)
   rom-factory (= 0.12.0)
   rspec-rails (= 6.1.2)
+  rswag-api (= 2.13.0)
+  rswag-specs (= 2.13.0)
+  rswag-ui (= 2.13.0)
+  simplecov (= 0.22.0)
   standard (= 1.35.1)
 
 RUBY VERSION

app/controllers/v1/auctions_controller.rb

@@ -1,18 +1,21 @@
 # frozen_string_literal: true
 
 module V1
-  # Main class (Add doc)
   class AuctionsController < ApplicationController
     def index
-      auctions = auction_relation.all(params[:page] || 1, params[:per_page] || 25).to_a
+      auctions = auction_relation.all(index_params).to_a
 
-      render json: {auctions: auctions}, status: :ok
+      render json: auctions, status: :ok
     end
 
     private
 
     def auction_relation
       AuctionFunCore::Application[:container].relations[:auctions]
     end
+
+    def index_params
+      params.permit!
+    end
   end
 end

config/initializers/rswag.rb

@@ -0,0 +1,29 @@
+Rswag::Api.configure do |c|
+  # Specify a root folder where Swagger JSON files are located
+  # This is used by the Swagger middleware to serve requests for API descriptions
+  # NOTE: If you're using rswag-specs to generate Swagger, you'll need to ensure
+  # that it's configured to generate files in the same folder
+  c.openapi_root = Rails.root.to_s + "/swagger"
+
+  # Inject a lambda function to alter the returned Swagger prior to serialization
+  # The function will have access to the rack env for the current request
+  # For example, you could leverage this to dynamically assign the "host" property
+  #
+  # c.swagger_filter = lambda { |swagger, env| swagger['host'] = env['HTTP_HOST'] }
+end
+
+Rswag::Ui.configure do |c|
+  # List the Swagger endpoints that you want to be documented through the
+  # swagger-ui. The first parameter is the path (absolute or relative to the UI
+  # host) to the corresponding endpoint and the second is a title that will be
+  # displayed in the document selector.
+  # NOTE: If you're using rspec-api to expose Swagger files
+  # (under openapi_root) as JSON or YAML endpoints, then the list below should
+  # correspond to the relative paths for those endpoints.
+
+  c.openapi_endpoint "/api-docs/v1/swagger.yaml", "API V1 Docs"
+
+  # Add Basic Auth in case your API is private
+  # c.basic_auth_enabled = true
+  # c.basic_auth_credentials 'username', 'password'
+end

config/routes.rb

@@ -1,4 +1,8 @@
 Rails.application.routes.draw do
+  # Reveal health status on /up that returns 200 if the app boots with no exceptions, otherwise 500.
+  # Can be used by load balancers and uptime monitors to verify that the app is live.
+  get "up" => "rails/health#show", :as => :rails_health_check
+
   if Rails.env.development?
     require "sidekiq/web"
 
@@ -7,11 +11,10 @@
     mount Sidekiq::Web => "/sidekiq"
   end
 
-  # Reveal health status on /up that returns 200 if the app boots with no exceptions, otherwise 500.
-  # Can be used by load balancers and uptime monitors to verify that the app is live.
-  get "up" => "rails/health#show", :as => :rails_health_check
+  mount Rswag::Ui::Engine => "/api-docs"
+  mount Rswag::Api::Engine => "/api-docs"
 
-  namespace :v1, defaults: {format: :json} do
+  namespace :v1, defaults: {format: :json}, constraints: {format: "json"} do
     resources :auctions, only: %i[index]
   end
 end

devops/development/osx/functions

@@ -25,3 +25,8 @@ function install_brew_dependencies {
 
   brew bundle --file=$BREWFILE
 }
+
+function install_git_hooks {
+  overcommit --install
+  overcommit --sign pre-commit
+}

devops/development/setup

@@ -18,6 +18,7 @@ case "$OSTYPE" in
 
         install_essential_packages
         source $PWD/devops/development/bin/asdf
+        install_git_hooks
       else
         echo "This setup only supports Ubuntu 22.04 as described in the README. You can run the project normally, but you will have to manually install the required packages according to your distribution."
         exit 0
@@ -30,6 +31,8 @@ case "$OSTYPE" in
     source devops/development/osx/functions
     install_osx_packages
     install_development_tools
+    source $PWD/devops/development/bin/asdf
+    install_git_hooks
     ;;
   *)
     echo "Unsupported operating system"

devops/development/ubuntu/functions

@@ -6,3 +6,7 @@ function install_essential_packages {
   sudo apt install -y $(awk '!/^ *#/ && NF > 0' "$APTFILE")
 }
 
+function install_git_hooks {
+  overcommit --install
+  overcommit --sign pre-commit
+}

spec/rails_helper.rb

@@ -1,4 +1,11 @@
-# This file is copied to spec/ when you run 'rails generate rspec:install'
+if ENV["CI"]
+  require "simplecov"
+  SimpleCov.start("rails") do
+    add_filter "lib/tasks"
+    add_filter "lib/templates"
+  end
+end
+
 require "spec_helper"
 ENV["RAILS_ENV"] ||= "test"
 require_relative "../config/environment"

spec/requests/auctions_spec.rb

@@ -0,0 +1,57 @@
+require "swagger_helper"
+
+describe "Auctions API" do
+  path "/auctions" do
+    get "Fetching auctions" do
+      tags "Auctions"
+      consumes "application/json"
+      produces "application/json"
+      parameter name: :page, in: :query, type: :integer, required: false, default: 1
+      parameter name: :per_page, in: :query, type: :integer, required: false, default: 10
+      parameter name: :bidders_count, in: :query, type: :integer, required: false, default: 3
+      request_body_example value: {}, name: "basic", summary: "Request example description"
+
+      response "200", "auction found" do
+        schema type: :array,
+          items: {
+            type: :object,
+            properties: {
+              id: {type: :integer, example: 1},
+              title: {type: :string, example: "Lightweight Iron Lamp"},
+              description: {type: :string, example: "Quo quidem veniam. Sunt tempora ratione. Aut culpa qui."},
+              started_at: {type: :string, format: :"date-time", example: "2024-04-30T18:04:51.156934"},
+              finished_at: {type: :string, format: :"date-time", example: "2024-04-30T18:04:51.156934"},
+              initial_bid_cents: {type: :integer, example: 100},
+              kind: {type: :string, example: "standard"},
+              status: {type: :string, example: "running"},
+              stopwatch: {type: :integer, example: 30},
+              total_bids: {type: :integer, example: 1},
+              bids: {
+                type: :object,
+                properties: {
+                  current: {type: :integer, example: 1000},
+                  minimal: {type: :integer, example: 1000},
+                  bidders: {
+                    type: :array,
+                    items: {
+                      type: :object,
+                      properties: {
+                        id: {type: :integer, example: 1},
+                        user_id: {type: :integer, example: 2},
+                        name: {type: :string, example: "Beatriz Louzada"},
+                        value: {type: :integer, example: 1000},
+                        date: {type: :string, format: :"date-time", example: "2024-04-30T18:04:51.156934"}
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          }
+
+        let!(:auction) { Factory[:auction, :default_running_standard, :with_one_bid] }
+        run_test!
+      end
+    end
+  end
+end

spec/support/requests.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-module ControllerHelpers
+module RequestsHelpers
   def json_response
     return if response.body.blank?
 
@@ -9,5 +9,5 @@ def json_response
 end
 
 RSpec.configure do |c|
-  c.include ControllerHelpers, type: :controller
+  c.include RequestsHelpers, type: :request
 end