Add Swagger docs for overland api endpoint

CHANGELOG.md

@@ -5,6 +5,14 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](http://keepachangelog.com/)
 and this project adheres to [Semantic Versioning](http://semver.org/).
 
+## [0.2.2] — 2024-05-18
+
+### Added
+
+- Swagger docs, can be found at `https:<your-host>/api-docs`
+
+---
+
 ## [0.2.1] — 2024-05-18
 
 ### Added
@@ -15,6 +23,8 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 
 - Dark/light theme switcher in navbar is now being saved in user settings, so it persists between sessions
 
+---
+
 ## [0.2.0] — 2024-05-05
 
 *Breaking changes:*
@@ -25,6 +35,8 @@ The logic behind this is the following: if you have a lot of points in a city, i
 
 In your docker-compose.yml file, you need to replace the `MINIMUM_POINTS_IN_CITY` environment variable with `MIN_MINUTES_SPENT_IN_CITY`. The default value is `60`, in minutes.
 
+---
+
 ## [0.1.9] — 2024-04-25
 
 ### Added
@@ -39,6 +51,7 @@ In your docker-compose.yml file, you need to replace the `MINIMUM_POINTS_IN_CITY
 
 - `ActiveStorage::FileNotFoundError` error when uploading export files
 
+---
 
 ## [0.1.8.1] — 2024-04-21
 
@@ -51,6 +64,8 @@ In your docker-compose.yml file, you need to replace the `MINIMUM_POINTS_IN_CITY
 - Consider timezone when parsing datetime params in points controller
 - Add rescue for check version service class
 
+---
+
 ## [0.1.8] — 2024-04-21
 
 ### Added
@@ -63,6 +78,8 @@ In your docker-compose.yml file, you need to replace the `MINIMUM_POINTS_IN_CITY
 
 - Disabled map points rendering by default to improve performance on big datasets
 
+---
+
 ## [0.1.7] — 2024-04-17
 
 ### Added
@@ -74,18 +91,24 @@ In your docker-compose.yml file, you need to replace the `MINIMUM_POINTS_IN_CITY
 - Added content padding for mobile view
 - Fixed stat card layout for mobile view
 
+---
+
 ## [0.1.6.3] — 2024-04-07
 
 ### Changed
 
 - Removed strong_params from POST /api/v1/points
 
+---
+
 ## [0.1.6.1] — 2024-04-06
 
 ### Fixed
 
 - `ActiveStorage::FileNotFoundError: ActiveStorage::FileNotFoundError` error when uploading export files
 
+---
+
 ## [0.1.6] — 2024-04-06
 
 You can now use [Overland](https://overland.p3k.app/) mobile app to track your location.
@@ -98,6 +121,8 @@ You can now use [Overland](https://overland.p3k.app/) mobile app to track your l
 
 ### Fixed
 
+---
+
 ## [0.1.5] — 2024-04-05
 
 You can now specify the host of the application by setting the `APPLICATION_HOST` environment variable in the `docker-compose.yml` file.

app/controllers/api/v1/overland/batches_controller.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 class Api::V1::Overland::BatchesController < ApplicationController
   skip_forgery_protection
 

app/jobs/overland/batch_creating_job.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 class Overland::BatchCreatingJob < ApplicationJob
   queue_as :default
 

spec/requests/api/v1/overland/batches_spec.rb

@@ -1,7 +1,9 @@
+# frozen_string_literal: true
+
 require 'rails_helper'
 
-RSpec.describe "Api::V1::Overland::Batches", type: :request do
-  describe "POST /index" do
+RSpec.describe 'Api::V1::Overland::Batches', type: :request do
+  describe 'POST /index' do
     let(:file_path) { 'spec/fixtures/files/overland/geodata.json' }
     let(:file) { File.open(file_path) }
     let(:json) { JSON.parse(file.read) }

spec/swagger/api/v1/overland/batches_controller_spec.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require 'swagger_helper'
+
+describe 'Batches API', type: :request do
+  path '/api/v1/overland/batches' do
+    post 'Creates a batch of points' do
+      request_body_example value: {
+        locations: [
+          {
+            type: 'Feature',
+            geometry: {
+              type: 'Point',
+              coordinates: [13.356718, 52.502397]
+            },
+            properties: {
+              timestamp: '2021-06-01T12:00:00Z',
+              altitude: 0,
+              speed: 0,
+              horizontal_accuracy: 0,
+              vertical_accuracy: 0,
+              motion: [],
+              pauses: false,
+              activity: 'unknown',
+              desired_accuracy: 0,
+              deferred: 0,
+              significant_change: 'unknown',
+              locations_in_payload: 1,
+              device_id: 'Swagger',
+              wifi: 'unknown',
+              battery_state: 'unknown',
+              battery_level: 0
+            }
+          }
+        ]
+      }
+      tags 'Batches'
+      consumes 'application/json'
+      parameter name: :locations, in: :body, schema: {
+        type: :object,
+        properties: {
+          type: { type: :string },
+          geometry: {
+            type: :object,
+            properties: {
+              type: { type: :string },
+              coordinates: { type: :array }
+            }
+          },
+          properties: {
+            type: :object,
+            properties: {
+              timestamp: { type: :string },
+              altitude: { type: :number },
+              speed: { type: :number },
+              horizontal_accuracy: { type: :number },
+              vertical_accuracy: { type: :number },
+              motion: { type: :array },
+              pauses: { type: :boolean },
+              activity: { type: :string },
+              desired_accuracy: { type: :number },
+              deferred: { type: :number },
+              significant_change: { type: :string },
+              locations_in_payload: { type: :number },
+              device_id: { type: :string },
+              wifi: { type: :string },
+              battery_state: { type: :string },
+              battery_level: { type: :number }
+            }
+          },
+        required: %w[geometry properties]
+        }
+      }
+
+      response '201', 'Batch of points created' do
+        let(:file_path) { 'spec/fixtures/files/overland/geodata.json' }
+        let(:file) { File.open(file_path) }
+        let(:json) { JSON.parse(file.read) }
+        let(:params) { json }
+        let(:locations) { params['locations'] }
+
+        run_test!
+      end
+    end
+  end
+end

swagger/v1/swagger.yaml

@@ -4,6 +4,96 @@ info:
   title: API V1
   version: v1
 paths:
+  "/api/v1/overland/batches":
+    post:
+      summary: Creates a batch of points
+      tags:
+      - Batches
+      parameters: []
+      responses:
+        '201':
+          description: Batch of points created
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                type:
+                  type: string
+                geometry:
+                  type: object
+                  properties:
+                    type:
+                      type: string
+                    coordinates:
+                      type: array
+                properties:
+                  type: object
+                  properties:
+                    timestamp:
+                      type: string
+                    altitude:
+                      type: number
+                    speed:
+                      type: number
+                    horizontal_accuracy:
+                      type: number
+                    vertical_accuracy:
+                      type: number
+                    motion:
+                      type: array
+                    pauses:
+                      type: boolean
+                    activity:
+                      type: string
+                    desired_accuracy:
+                      type: number
+                    deferred:
+                      type: number
+                    significant_change:
+                      type: string
+                    locations_in_payload:
+                      type: number
+                    device_id:
+                      type: string
+                    wifi:
+                      type: string
+                    battery_state:
+                      type: string
+                    battery_level:
+                      type: number
+                required:
+                - geometry
+                - properties
+            examples:
+              '0':
+                summary: Creates a batch of points
+                value:
+                  locations:
+                  - type: FeatureCollection
+                    geometry:
+                      type: Point
+                      coordinates:
+                      - 13.356718
+                      - 52.502397
+                    properties:
+                      timestamp: '2021-06-01T12:00:00Z'
+                      altitude: 0
+                      speed: 0
+                      horizontal_accuracy: 0
+                      vertical_accuracy: 0
+                      motion: []
+                      pauses: false
+                      activity: unknown
+                      desired_accuracy: 0
+                      deferred: 0
+                      significant_change: unknown
+                      locations_in_payload: 1
+                      device_id: Swagger
+                      wifi: unknown
+                      battery_state: unknown
+                      battery_level: 0
   "/api/v1/points":
     post:
       summary: Creates a point
@@ -82,7 +172,7 @@ paths:
                   lat: 52.502397
                   lon: 13.356718
                   tid: Swagger
-                  tst: 1716032145
+                  tst: 1716033410
 servers:
 - url: http://{defaultHost}
   variables: