Swagger setup

.env.example

@@ -61,4 +61,5 @@ SEED_DATA_FROM_CSV=true
 
 SEND_INVOICE_EMAILS=true
 
-CI=true
+CI=true
+

Gemfile

@@ -144,6 +144,10 @@ gem "httparty"
 # Use google calendar for integration with Miru
 gem "google-api-client", require: "google/apis/calendar_v3"
 
+# Swagger
+gem "rswag-api"
+gem "rswag-ui"
+
 group :development, :test, :ci do
   # See https://edgeguides.rubyonrails.org/debugging_rails_applications.html#debugging-with-the-debug-gem
   gem "debug", ">= 1.0.0", platforms: %i[mri mingw x64_mingw]
@@ -181,6 +185,8 @@ group :development, :test, :ci do
   gem "webmock", "~> 3.14.0"
 
   gem "dockerfile-rails"
+
+  gem "rswag-specs"
 end
 
 group :development do

Gemfile.lock

@@ -294,6 +294,8 @@ GEM
       railties (>= 4.2.0)
       thor (>= 0.14, < 2.0)
     json (2.6.3)
+    json-schema (3.0.0)
+      addressable (>= 2.8)
     jwt (2.7.0)
     kaminari (1.2.2)
       activesupport (>= 4.1.0)
@@ -488,6 +490,16 @@ GEM
       rspec-core (~> 3.0, >= 3.0.0)
       sidekiq (>= 2.4.0)
     rspec-support (3.12.0)
+    rswag-api (2.11.0)
+      railties (>= 3.1, < 7.2)
+    rswag-specs (2.11.0)
+      activesupport (>= 3.1, < 7.2)
+      json-schema (>= 2.2, < 4.0)
+      railties (>= 3.1, < 7.2)
+      rspec-core (>= 2.14)
+    rswag-ui (2.11.0)
+      actionpack (>= 3.1, < 7.2)
+      railties (>= 3.1, < 7.2)
     rubocop (1.44.1)
       json (~> 2.3)
       parallel (~> 1.10)
@@ -684,6 +696,9 @@ DEPENDENCIES
   rspec-rails (~> 5.0, >= 5.0.2)
   rspec-retry
   rspec-sidekiq
+  rswag-api
+  rswag-specs
+  rswag-ui
   rubocop
   rubocop-performance
   rubocop-rails

config/initializers/rswag_api.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+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.swagger_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

config/initializers/rswag_ui.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+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 swagger_root) as JSON or YAML endpoints, then the list below should
+  # correspond to the relative paths for those endpoints.
+
+  c.swagger_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

@@ -9,6 +9,8 @@ def draw(routes_name)
 end
 
 Rails.application.routes.draw do
+  mount Rswag::Ui::Engine => "/api-docs"
+  mount Rswag::Api::Engine => "/api-docs"
   namespace :admin do
       resources :users
       resources :timesheet_entries

spec/swagger_helper.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require "rails_helper"
+
+RSpec.configure do |config|
+  # Specify a root folder where Swagger JSON files are generated
+  # NOTE: If you're using the rswag-api to serve API descriptions, you'll need
+  # to ensure that it's configured to serve Swagger from the same folder
+  config.swagger_root = Rails.root.join("swagger").to_s
+
+  # Define one or more Swagger documents and provide global metadata for each one
+  # When you run the 'rswag:specs:swaggerize' rake task, the complete Swagger will
+  # be generated at the provided relative path under swagger_root
+  # By default, the operations defined in spec files are added to the first
+  # document below. You can override this behavior by adding a swagger_doc tag to the
+  # the root example_group in your specs, e.g. describe '...', swagger_doc: 'v2/swagger.json'
+  config.swagger_docs = {
+    "v1/swagger.yaml" => {
+      openapi: "3.0.1",
+      info: {
+        title: "API V1",
+        version: "v1"
+      },
+      paths: {},
+      servers: [
+        {
+          url: ENV["APP_BASE_URL"],
+          variables: {
+            defaultHost: {
+              default: "localhost:3000"
+            }
+          }
+        }
+      ]
+    }
+  }
+
+  # Specify the format of the output Swagger file when running 'rswag:specs:swaggerize'.
+  # The swagger_docs configuration option has the filename including format in
+  # the key, this may want to be changed to avoid putting yaml in json files.
+  # Defaults to json. Accepts ':json' and ':yaml'.
+  config.swagger_format = :yaml
+end

swagger/v1/swagger.yaml

@@ -0,0 +1,11 @@
+---
+openapi: 3.0.1
+info:
+  title: API V1
+  version: v1
+paths: {}
+servers:
+- url: http://localhost:3000
+  variables:
+    defaultHost:
+      default: localhost:3000