chore: update candidates Swagger documentation

andrecego · Feb 9, 2024 · 1e65381 · 1e65381
1 parent 17ca29a
commit 1e65381
Show file tree

Hide file tree

Showing 2 changed files with 88 additions and 4 deletions.
diff --git a/spec/requests/api/v1/candidates_request_swagger_spec.rb b/spec/requests/api/v1/candidates_request_swagger_spec.rb
@@ -4,17 +4,55 @@
 
 describe 'Candidates API' do
   path '/api/v1/candidates' do
+    get 'Retrieves a list of candidates' do
+      tags 'Candidates'
+      produces 'application/json'
+      parameter name: :page, in: :query, type: :integer
+      parameter name: :per_page, in: :query, type: :integer
+
+      response '200', 'Candidates list' do
+        schema type:       :object,
+               properties: {
+                 candidates: {
+                   type:  :array,
+                   items: {
+                     type:       :object,
+                     properties: {
+                       id:        { type: :integer },
+                       name:      { type: :string },
+                       email:     { type: :string },
+                       birthdate: { type: :string, format: :date }
+                     }
+                   }
+                 },
+                 meta:       {
+                   type:       :object,
+                   properties: {
+                     page:        { type: :integer },
+                     per_page:    { type: :integer },
+                     total_pages: { type: :integer },
+                     total_count: { type: :integer }
+                   }
+                 }
+               }
+
+        let(:page) { 1 }
+        let(:per_page) { 20 }
+        run_test!
+      end
+    end
+
     post 'Creates a candidate' do
       tags 'Candidates'
       consumes 'application/json'
       parameter name: :candidate, in: :body, schema: {
-        type: :object,
+        type:       :object,
         properties: {
-          name: { type: :string, example: 'Andre' },
-          email: { type: :string, format: :email, example: 'andre@haistack.ai' },
+          name:      { type: :string, example: 'Andre' },
+          email:     { type: :string, format: :email, example: 'andre@haistack.ai' },
           birthdate: { type: :string, format: :date, example: '1992-04-27' }
         },
-        required: %w[name email birthdate]
+        required:   %w[name email birthdate]
       }
 
       response '201', 'Candidate created' do

diff --git a/swagger/v1/swagger.yaml b/swagger/v1/swagger.yaml
@@ -5,6 +5,52 @@ info:
   version: v1
 paths:
   "/api/v1/candidates":
+    get:
+      summary: Retrieves a list of candidates
+      tags:
+      - Candidates
+      parameters:
+      - name: page
+        in: query
+        schema:
+          type: integer
+      - name: per_page
+        in: query
+        schema:
+          type: integer
+      responses:
+        '200':
+          description: Candidates list
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  candidates:
+                    type: array
+                    items:
+                      type: object
+                      properties:
+                        id:
+                          type: integer
+                        name:
+                          type: string
+                        email:
+                          type: string
+                        birthdate:
+                          type: string
+                          format: date
+                  meta:
+                    type: object
+                    properties:
+                      page:
+                        type: integer
+                      per_page:
+                        type: integer
+                      total_pages:
+                        type: integer
+                      total_count:
+                        type: integer
     post:
       summary: Creates a candidate
       tags: