Feat: Add RSwag to generate API Documentation

README.md

@@ -65,6 +65,10 @@ rake run
 
 Visit your app at [http://localhost:4300](http://localhost:4300)
 
+### Open API Documentation
+This project is using the [rswag](https://github.com/rswag/rswag) gem to generate interactive api documentation. You can access this documentation locally at [http://localhost:3000/api-docs/index.html](http://localhost:3000/api-docs/index.html).
+If you make changes to the api, you will need to run `bundle exec rake rswag` from the backend directory to update the generated examples.
+
 ## CI
 
 Several checks are configured to run on all commits using Github Actions, including lint, build and test steps. Definitions can be found in [./github/workflows](./github/workflows). Those checks which always run are required to be successful for PRs to be mergable.

backend/Gemfile

@@ -62,6 +62,8 @@ gem "kaminari-actionview"
 gem "kaminari-mongoid"
 gem "rack-cors", "1.1.1", require: "rack/cors" # freezing to gemfile.lock version because heroku is not respecting lockfile
 gem "simplecov", require: false, group: :test
+gem "rswag-api"
+gem "rswag-ui"
 
 group :development, :test do
   # Call 'byebug' anywhere in the code to stop execution and get a debugger console
@@ -78,6 +80,7 @@ group :development, :test do
   gem "pry-rails"
   gem "rspec-rails"
   gem "standardrb"
+  gem "rswag-specs"
 end
 
 group :development do

backend/Gemfile.lock

@@ -193,6 +193,8 @@ GEM
     i18n_data (0.13.0)
     json (2.6.3)
     json (2.6.3-java)
+    json-schema (3.0.0)
+      addressable (>= 2.8)
     jwt (2.3.0)
     kaminari-actionview (1.2.1)
       actionview
@@ -381,6 +383,16 @@ GEM
       rspec-mocks (~> 3.12)
       rspec-support (~> 3.12)
     rspec-support (3.12.1)
+    rswag-api (2.10.1)
+      railties (>= 3.1, < 7.1)
+    rswag-specs (2.10.1)
+      activesupport (>= 3.1, < 7.1)
+      json-schema (>= 2.2, < 4.0)
+      railties (>= 3.1, < 7.1)
+      rspec-core (>= 2.14)
+    rswag-ui (2.10.1)
+      actionpack (>= 3.1, < 7.1)
+      railties (>= 3.1, < 7.1)
     rubocop (1.52.1)
       json (~> 2.3)
       parallel (~> 1.10)
@@ -515,6 +527,9 @@ DEPENDENCIES
   rails_12factor
   rake
   rspec-rails
+  rswag-api
+  rswag-specs
+  rswag-ui
   ruby-progressbar
   seedbank
   shoulda-matchers

backend/Rakefile

@@ -2,4 +2,13 @@
 # for example lib/tasks/capistrano.rake, and they will automatically be available to Rake.
 
 require File.expand_path("../config/application", __FILE__)
+require_relative "config/application"
+
+# Workaround for https://github.com/rswag/rswag/issues/359
+if defined? RSpec
+  RSpec.configure do |config|
+    config.swagger_dry_run = false
+  end
+end
+
 Rails.application.load_tasks

backend/config/initializers/rswag_api.rb

@@ -0,0 +1,13 @@
+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

backend/config/initializers/rswag_ui.rb

@@ -0,0 +1,15 @@
+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

backend/config/routes.rb

@@ -1,6 +1,11 @@
 # rubocop:disable Metrics/BlockLength
 
 Rails.application.routes.draw do
+  if Rails.env.development?
+    mount Rswag::Ui::Engine => "/api-docs"
+    mount Rswag::Api::Engine => "/api-docs"
+  end
+
   root "application#root"
 
   # Authentication

backend/spec/requests/api/v1/checkins_spec.rb

@@ -0,0 +1,86 @@
+require "swagger_helper"
+
+RSpec.describe "api/v1/checkins", type: :request do
+  path "/api/checkins" do
+    get("list checkins") do
+      response(200, "successful") do
+        after do |example|
+          example.metadata[:response][:content] = {
+            "application/json" => {
+              example: JSON.parse(response.body, symbolize_names: true)
+            }
+          }
+        end
+        pending "Not yet implemented, when implemented uncomment the assertion below"
+        # run_test!
+      end
+    end
+
+    post("create checkin") do
+      response(200, "successful") do
+        after do |example|
+          example.metadata[:response][:content] = {
+            "application/json" => {
+              example: JSON.parse(response.body, symbolize_names: true)
+            }
+          }
+        end
+        pending "Not yet implemented, when implemented uncomment the assertion below"
+        # run_test!
+      end
+    end
+  end
+
+  path "/api/checkins/{id}" do
+    # You'll want to customize the parameter types...
+    parameter name: "id", in: :path, type: :string, description: "id"
+
+    get("show checkin") do
+      response(200, "successful") do
+        let(:id) { "123" }
+
+        after do |example|
+          example.metadata[:response][:content] = {
+            "application/json" => {
+              example: JSON.parse(response.body, symbolize_names: true)
+            }
+          }
+        end
+        pending "Not yet implemented, when implemented uncomment the assertion below"
+        # run_test!
+      end
+    end
+
+    patch("update checkin") do
+      response(200, "successful") do
+        let(:id) { "123" }
+
+        after do |example|
+          example.metadata[:response][:content] = {
+            "application/json" => {
+              example: JSON.parse(response.body, symbolize_names: true)
+            }
+          }
+        end
+        pending "Not yet implemented, when implemented uncomment the assertion below"
+        # run_test!
+      end
+    end
+
+    put("update checkin") do
+      response(200, "successful") do
+        let(:id) { "123" }
+
+        after do |example|
+          example.metadata[:response][:content] = {
+            "application/json" => {
+              example: JSON.parse(response.body, symbolize_names: true)
+            }
+          }
+        end
+        pending "Not yet implemented, when implemented uncomment the assertion below"
+        # run_test!
+      end
+    end
+  end
+end

backend/spec/requests/api/v1/conditions_spec.rb

@@ -0,0 +1,54 @@
+require "swagger_helper"
+
+RSpec.describe "api/v1/conditions", type: :request do
+  path "/api/conditions" do
+    get("list conditions") do
+      response(200, "successful") do
+        after do |example|
+          example.metadata[:response][:content] = {
+            "application/json" => {
+              example: JSON.parse(response.body, symbolize_names: true)
+            }
+          }
+        end
+        pending "Not yet implemented, when implemented uncomment the assertion below"
+        # run_test!
+      end
+    end
+
+    post("create condition") do
+      response(200, "successful") do
+        after do |example|
+          example.metadata[:response][:content] = {
+            "application/json" => {
+              example: JSON.parse(response.body, symbolize_names: true)
+            }
+          }
+        end
+        pending "Not yet implemented, when implemented uncomment the assertion below"
+        # run_test!
+      end
+    end
+  end
+
+  path "/api/conditions/{id}" do
+    # You'll want to customize the parameter types...
+    parameter name: "id", in: :path, type: :string, description: "id"
+
+    get("show condition") do
+      response(200, "successful") do
+        let(:id) { "123" }
+
+        after do |example|
+          example.metadata[:response][:content] = {
+            "application/json" => {
+              example: JSON.parse(response.body, symbolize_names: true)
+            }
+          }
+        end
+        pending "Not yet implemented, when implemented uncomment the assertion below"
+        # run_test!
+      end
+    end
+  end
+end

backend/spec/requests/api/v1/countries_spec.rb

@@ -0,0 +1,38 @@
+require "swagger_helper"
+
+RSpec.describe "api/v1/countries", type: :request do
+  path "/api/countries" do
+    get("list countries") do
+      response(200, "successful") do
+        after do |example|
+          example.metadata[:response][:content] = {
+            "application/json" => {
+              example: JSON.parse(response.body, symbolize_names: true)
+            }
+          }
+        end
+        run_test!
+      end
+    end
+  end
+
+  path "/api/countries/{id}" do
+    # You'll want to customize the parameter types...
+    parameter name: "id", in: :path, type: :string, description: "id"
+
+    get("show country") do
+      response(200, "successful") do
+        let(:id) { "US" }
+
+        after do |example|
+          example.metadata[:response][:content] = {
+            "application/json" => {
+              example: JSON.parse(response.body, symbolize_names: true)
+            }
+          }
+        end
+        run_test!
+      end
+    end
+  end
+end

backend/spec/requests/api/v1/day_habits_spec.rb

@@ -0,0 +1,40 @@
+require "swagger_helper"
+
+RSpec.describe "api/v1/day_habits", type: :request do
+  path "/api/day_habits" do
+    get("list day_habits") do
+      response(200, "successful") do
+        after do |example|
+          example.metadata[:response][:content] = {
+            "application/json" => {
+              example: JSON.parse(response.body, symbolize_names: true)
+            }
+          }
+        end
+        pending "Not yet implemented, when implemented uncomment the assertion below"
+        # run_test!
+      end
+    end
+  end
+
+  path "/api/day_habits/{id}" do
+    # You'll want to customize the parameter types...
+    parameter name: "id", in: :path, type: :string, description: "id"
+
+    get("show day_habit") do
+      response(200, "successful") do
+        let(:id) { "123" }
+
+        after do |example|
+          example.metadata[:response][:content] = {
+            "application/json" => {
+              example: JSON.parse(response.body, symbolize_names: true)
+            }
+          }
+        end
+        pending "Not yet implemented, when implemented uncomment the assertion below"
+        # run_test!
+      end
+    end
+  end
+end

backend/spec/requests/api/v1/education_levels_spec.rb

@@ -0,0 +1,40 @@
+require "swagger_helper"
+
+RSpec.describe "api/v1/education_levels", type: :request do
+  path "/api/education_levels" do
+    get("list education_levels") do
+      response(200, "successful") do
+        after do |example|
+          example.metadata[:response][:content] = {
+            "application/json" => {
+              example: JSON.parse(response.body, symbolize_names: true)
+            }
+          }
+        end
+        pending "Not yet implemented, when implemented uncomment the assertion below"
+        # run_test!
+      end
+    end
+  end
+
+  path "/api/education_levels/{id}" do
+    # You'll want to customize the parameter types...
+    parameter name: "id", in: :path, type: :string, description: "id"
+
+    get("show education_level") do
+      response(200, "successful") do
+        let(:id) { "123" }
+
+        after do |example|
+          example.metadata[:response][:content] = {
+            "application/json" => {
+              example: JSON.parse(response.body, symbolize_names: true)
+            }
+          }
+        end
+        pending "Not yet implemented, when implemented uncomment the assertion below"
+        # run_test!
+      end
+    end
+  end
+end