Add Endpoints Documentation with rswag

README.md

@@ -198,4 +198,5 @@ Backend using [Render](https://render.com/).
 
 ## API Endpoint Documentation
 
-All BE endpoints are detailed [here]() (Work in progress...)
+All backend endpoints are detailed [here](https://finder-backend-prod.onrender.com/api-docs).
+Includes information about the path, parameters and body for each request, and response examples.

api/Gemfile

@@ -12,13 +12,16 @@ gem 'jsonapi-serializer', '~> 2.2'
 gem 'pg', '~> 1.1'
 gem 'puma', '~> 5.0'
 gem 'rack-cors', '~> 2.0'
+gem 'rswag-api', '~> 2.10'
+gem 'rswag-ui', '~> 2.10'
 gem 'sendgrid-ruby', '~> 6.0'
 gem 'tzinfo-data', platforms: %i[mingw mswin x64_mingw jruby]
 
 group :development, :test do
   gem 'debug', platforms: %i[mri mingw x64_mingw]
   gem 'factory_bot_rails', '~> 6.2'
   gem 'rspec-rails', '~> 6.0'
+  gem 'rswag-specs', '~> 2.10'
   gem 'simplecov', '~> 0.22'
 end
 

api/Gemfile.lock

@@ -66,6 +66,8 @@ GEM
       i18n (>= 1.6, < 2)
       minitest (>= 5.1)
       tzinfo (~> 2.0)
+    addressable (2.8.5)
+      public_suffix (>= 2.0.2, < 6.0)
     ast (2.4.2)
     base64 (0.1.1)
     bcrypt (3.1.19)
@@ -112,6 +114,8 @@ GEM
     irb (1.7.4)
       reline (>= 0.3.6)
     json (2.6.3)
+    json-schema (3.0.0)
+      addressable (>= 2.8)
     jsonapi-serializer (2.2.0)
       activesupport (>= 4.2)
     jwt (2.7.1)
@@ -151,6 +155,7 @@ GEM
       ast (~> 2.4.1)
       racc
     pg (1.5.3)
+    public_suffix (5.0.3)
     puma (5.6.7)
       nio4r (~> 2.0)
     racc (1.7.1)
@@ -213,6 +218,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.56.1)
       base64 (~> 0.1.1)
       json (~> 2.3)
@@ -277,6 +292,9 @@ DEPENDENCIES
   rack-cors (~> 2.0)
   rails (~> 7.0.7, >= 7.0.7.2)
   rspec-rails (~> 6.0)
+  rswag-api (~> 2.10)
+  rswag-specs (~> 2.10)
+  rswag-ui (~> 2.10)
   rubocop-rails
   sendgrid-ruby (~> 6.0)
   shoulda-matchers (~> 5.0)

api/config/environments/development.rb

@@ -90,6 +90,9 @@
   # Highlight code that triggered database queries in logs.
   config.active_record.verbose_query_logs = true
 
-  # Front base url
+  # BE base URL
+  config.api_base_url = 'http://localhost:3000/'
+
+  # FE base URL
   config.client_base_url = 'http://localhost:3333/'
 end

api/config/environments/production.rb

@@ -102,6 +102,9 @@
     config.logger = ActiveSupport::TaggedLogging.new(logger)
   end
 
-  # Front base url
+  # BE base URL
+  config.api_base_url = 'http://finder-backend-prod.onrender.com/'
+
+  # FE base URL
   config.client_base_url = 'https://finder-tau.vercel.app/'
 end

api/config/environments/staging.rb

@@ -102,6 +102,9 @@
     config.logger    = ActiveSupport::TaggedLogging.new(logger)
   end
 
-  # Front base url
+  # BE base URL
+  config.api_base_url = 'https://finder-backend-qa.onrender.com/'
+
+  # FE base URL
   config.client_base_url = 'https://finder-git-develop-frodo2412.vercel.app/'
 end

api/config/environments/test.rb

@@ -92,6 +92,9 @@
   # Highlight code that triggered database queries in logs.
   config.active_record.verbose_query_logs = true
 
-  # Front base url
-  config.client_base_url = 'https://finder-git-develop-frodo2412.vercel.app/'
+  # BE base URL
+  config.api_base_url = 'http://localhost:3000/'
+
+  # FE base URL
+  config.client_base_url = 'http://localhost:3333/'
 end

api/config/initializers/rswag_api.rb

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

api/config/initializers/rswag_ui.rb

@@ -0,0 +1,16 @@
+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.json', 'API V1 Docs'
+
+  # Add Basic Auth in case your API is private
+  # c.basic_auth_enabled = true
+  # c.basic_auth_credentials 'username', 'password'
+end

api/config/routes.rb

@@ -15,15 +15,18 @@
 
   resources :attendances, only: :update
   resources :careers, only: :index
-  resources :groups, except: [:new, :edit] do
+  resources :groups do
     get :members, on: :member
+    resources :messages, module: :groups, except: :show
     resources :requests, only: [:create, :index, :update], module: :groups do
       get 'users/:user_id', to: 'requests#show_for_user', on: :collection
     end
-    resources :messages, module: :groups, except: :show
   end
   resources :members, only: [:update, :destroy]
   resources :sessions, only: [:create, :show, :update, :destroy]
   resources :subjects, only: [:index, :show]
   resources :users, only: [:show, :update, :destroy]
+
+  mount Rswag::Ui::Engine => '/api-docs'
+  mount Rswag::Api::Engine => '/api-docs'
 end

api/spec/api/attendances_spec.rb

@@ -0,0 +1,53 @@
+require 'swagger_helper'
+
+RSpec.describe 'attendances', type: :request do
+  # Authorization
+  let(:user) { attendance_to_update.member.user }
+  let(:headers) do
+    post user_session_path, params: { user: { email: user.email, password: user.password } }
+
+    response.headers
+  end
+
+  # Update
+  path '/attendances/{id}' do
+    patch 'Updates an attendance' do
+      tags 'Attendances'
+      consumes 'application/json'
+      produces 'application/json'
+      parameter name: :id, in: :path, type: :integer, required: true, description: 'Attendance ID'
+      parameter name: :attendance, in: :body, schema: {
+        type: :object,
+        properties: {
+          status: { type: :string }
+        },
+        required: ['attendance']
+      }
+      parameter name: 'Authorization', in: :header, type: :string, value: 'Bearer <JWT Token>'
+
+      response '200', 'Success' do
+        let(:attendance_to_update) { create :attendance }
+        let(:id) { attendance_to_update.id }
+        let(:group) { attendance_to_update.session.group }
+        let(:attendance) { { status: 'accepted' } }
+        let('Authorization') do
+          headers['Authorization']
+        end
+
+        before do
+          create(:member, role: 'participant', user:, group:)
+        end
+
+        generate_swagger_response('update_attendances')
+        run_test! do |response|
+          json_response = JSON.parse(response.body)
+
+          expect(json_response['id']).to eq(attendance_to_update.id)
+          expect(json_response['status']).to eq(attendance[:status])
+          expect(json_response['session_id']).to eq(attendance_to_update.session_id)
+          expect(json_response['member_id']).to eq(attendance_to_update.member_id)
+        end
+      end
+    end
+  end
+end

api/spec/api/careers_spec.rb

@@ -0,0 +1,42 @@
+require 'swagger_helper'
+
+RSpec.describe 'careers', type: :request do
+  # Authorization
+  let(:user) { create :user }
+  let(:headers) do
+    post user_session_path, params: { user: { email: user.email, password: user.password } }
+
+    response.headers
+  end
+
+  # Index
+  path '/careers' do
+    get 'Returns all careers' do
+      tags 'Careers'
+      produces 'application/json'
+      parameter name: 'Authorization', in: :header, type: :string, value: 'Bearer <JWT Token>'
+
+      before do
+        create_list(:career, 2)
+      end
+
+      response '200', 'Success' do
+        let('Authorization') do
+          headers['Authorization']
+        end
+
+        generate_swagger_response('index_careers')
+        run_test! do |response|
+          json_response = JSON.parse(response.body)
+
+          expect(json_response[0]['id']).to be_a(Integer)
+          expect(json_response[0]['name']).to be_a(String)
+          expect(json_response[0]['code']).to be_a(String)
+          expect(json_response[0]['approved_on']).to be_a(String)
+          expect(json_response[0]['years']).to be_a(Integer)
+          expect(json_response[0]['credits']).to be_a(Integer)
+        end
+      end
+    end
+  end
+end