apply coding rules to openAPI doc

app/doc/open_api/api_doc.rb

@@ -1,8 +1,9 @@
+# frozen_string_literal: true
+
 # app/concerns/controllers/api_doc.rb
 #
 # Controller extension with common API documentation shortcuts
 #
-
 module OpenAPI::ApiDoc
   # Apipie doesn't allow to append anything to esisting
   #  description. It raises an error on double definition.

app/doc/open_api/application_doc.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 # app/docs/application_doc.rb
 #
 # A common class for defining API docs
@@ -16,7 +18,6 @@
 #     end
 #   end
 #
-
 class OpenAPI::ApplicationDoc
   extend OpenAPI::ApiDoc
 

app/doc/open_api/v1/base_doc.rb

@@ -1,5 +1,8 @@
+# frozen_string_literal: true
+
+# parent class for openAPI documentation
 class OpenAPI::V1::BaseDoc < OpenAPI::ApplicationDoc
-  API_VERSION = "v1"
+  API_VERSION = 'v1'
-  FORMATS = ['json']
+  FORMATS = ['json'].freeze
   PER_PAGE_DEFAULT = 20
 end

app/doc/open_api/v1/bookable_machines_doc.rb

@@ -1,3 +1,6 @@
+# frozen_string_literal: true
+
+# openAPI documentation for bookable machines endpoint
 class OpenAPI::V1::BookableMachinesDoc < OpenAPI::V1::BaseDoc
   resource_description do
     short 'Bookable machines'
@@ -7,10 +10,10 @@ class OpenAPI::V1::BookableMachinesDoc < OpenAPI::V1::BaseDoc
   end
 
   doc_for :index do
-    api :GET, "/#{API_VERSION}/bookable_machines", "Bookable machines index"
+    api :GET, "/#{API_VERSION}/bookable_machines", 'Bookable machines index'
-    description "Machines that a given user is allowed to book."
+    description 'Machines that a given user is allowed to book.'
-    param :user_id, Integer, required: true, desc: "Id of the given user."
+    param :user_id, Integer, required: true, desc: 'Id of the given user.'
-    example <<-EOS
+    example <<-MACHINES
       # /open_api/v1/bookable_machines?user_id=522
       {
         "machines": [
@@ -67,6 +70,6 @@ class OpenAPI::V1::BookableMachinesDoc < OpenAPI::V1::BaseDoc
           # ...
         ]
       }
-    EOS
+    MACHINES
   end
 end

app/doc/open_api/v1/concerns/param_groups.rb

@@ -1,30 +1,13 @@
+# frozen_string_literal: true
+
+# openAPI pagination
 module OpenAPI::V1::Concerns::ParamGroups
   extend ActiveSupport::Concern
 
   included do
     define_param_group :pagination do
-      param :page, Integer, desc: "Page number", optional: true
+      param :page, Integer, desc: 'Page number', optional: true
       param :per_page, Integer, desc: "Number of objects per page. Default is #{OpenAPI::V1::BaseDoc::PER_PAGE_DEFAULT}.", optional: true
     end
-
-    # define_param_group :order_type do
-    #   param :order_type, ['asc', 'desc'], desc: "order type: descendant or ascendant. Default value is *desc*."
-    # end
-    #
-    # define_param_group :filter_by_tags do
-    #   param :tagged_with, [String, Array], desc: 'If multiple tags are given, we use an *OR* function. See parameter *order_by_matching_tag_count* to order the result. It can also be a *comma* *separated* *string*. Example: tagged_with=science,museum'
-    #   param :order_by_matching_tag_count, ['t',1,'true'], desc: "You can use this parameter if you are sending a parameter *tagged_with*. Send this parameter to order by number of matching tags (descendant): result will be sort firstly by matching tags and secondly by order given by *order_by* parameter. Default to *false*."
-    # end
-    #
-    # define_param_group :filter_by_blog do
-    #   param :blog_slug, String, desc: "Send the blog's *slug* to only return articles belonging to specific blog."
-    # end
-    #
-    # define_param_group :filter_by_geolocation do
-    #   param :latitude, Numeric, desc: "Latitude. Example: *45.166670*"
-    #   param :longitude, Numeric, desc: "Longitude. Example: *5.7166700*"
-    #   param :radius, Numeric, desc: "To be combined with parameters latitude and longitude. Default to *10*."
-    #   param :order_by_distance, ['t',1,'true'], desc: "You can use this parameter if you are sending parameters *latitude* and *longitude*. Send this parameter to order by distance (descendant): result will be sort firstly by distance and secondly by order given by *order_by* parameter. Default to *false*."
-    # end
   end
 end

app/doc/open_api/v1/events_doc.rb

@@ -1,3 +1,6 @@
+# frozen_string_literal: true
+
+# openAPI documentation for events endpoint
 class OpenAPI::V1::EventsDoc < OpenAPI::V1::BaseDoc
   resource_description do
     short 'Events'
@@ -9,12 +12,12 @@ class OpenAPI::V1::EventsDoc < OpenAPI::V1::BaseDoc
   include OpenAPI::V1::Concerns::ParamGroups
 
   doc_for :index do
-    api :GET, "/#{API_VERSION}/events", "Events index"
+    api :GET, "/#{API_VERSION}/events", 'Events index'
     param_group :pagination
-	param :id, [Integer, Array], optional: true, desc: "Scope the request to one or various events."
+    param :id, [Integer, Array], optional: true, desc: 'Scope the request to one or various events.'
-	param :upcoming, [FalseClass, TrueClass], optional: true, desc: "Scope for the upcoming events."
+    param :upcoming, [FalseClass, TrueClass], optional: true, desc: 'Scope for the upcoming events.'
-    description "Events index. Order by *created_at* desc."
+    description 'Events index. Order by *created_at* desc.'
-    example <<-EOS
+    example <<-EVENTS
       # /open_api/v1/events?page=1&per_page=2
       {
         "events": [
@@ -54,6 +57,6 @@ class OpenAPI::V1::EventsDoc < OpenAPI::V1::BaseDoc
           }
         ]
       }
-    EOS
+    EVENTS
   end
 end

app/doc/open_api/v1/invoices_doc.rb

@@ -1,3 +1,6 @@
+# frozen_string_literal: true
+
+# openAPI documentation for invoices endpoints
 class OpenAPI::V1::InvoicesDoc < OpenAPI::V1::BaseDoc
   resource_description do
     short 'Invoices'
@@ -9,11 +12,11 @@ class OpenAPI::V1::InvoicesDoc < OpenAPI::V1::BaseDoc
   include OpenAPI::V1::Concerns::ParamGroups
 
   doc_for :index do
-    api :GET, "/#{API_VERSION}/invoices", "Invoices index"
+    api :GET, "/#{API_VERSION}/invoices", 'Invoices index'
     description "Index of users' invoices, with optional pagination. Order by *created_at* descendant."
     param_group :pagination
-    param :user_id, [Integer, Array], optional: true, desc: "Scope the request to one or various users."
+    param :user_id, [Integer, Array], optional: true, desc: 'Scope the request to one or various users.'
-    example <<-EOS
+    example <<-INVOICES
       # /open_api/v1/invoices?user_id=211&page=1&per_page=3
       {
         "invoices": [
@@ -64,15 +67,15 @@ class OpenAPI::V1::InvoicesDoc < OpenAPI::V1::BaseDoc
           }
         ]
       }
-    EOS
+    INVOICES
   end
 
   doc_for :download do
-      api :GET, "/#{API_VERSION}/invoices/:id/download", "Download an invoice"
+    api :GET, "/#{API_VERSION}/invoices/:id/download", 'Download an invoice'
-      param :id, Integer, desc: "Invoice id", required: true
+    param :id, Integer, desc: 'Invoice id', required: true
 
-      example <<-EOS
+    example <<-URL
       # /open_api/v1/invoices/2809/download
-      EOS
+    URL
   end
 end

app/doc/open_api/v1/machines_doc.rb

@@ -1,3 +1,6 @@
+# frozen_string_literal: true
+
+# openAPI documentation for machines endpoint
 class OpenAPI::V1::MachinesDoc < OpenAPI::V1::BaseDoc
   resource_description do
     short 'Machines'
@@ -7,9 +10,9 @@ class OpenAPI::V1::MachinesDoc < OpenAPI::V1::BaseDoc
   end
 
   doc_for :index do
-    api :GET, "/#{API_VERSION}/machines", "Machines index"
+    api :GET, "/#{API_VERSION}/machines", 'Machines index'
-    description "Machines index. Order by *created_at* ascendant."
+    description 'Machines index. Order by *created_at* ascendant.'
-    example <<-EOS
+    example <<-MACHINES
       # /open_api/v1/machines
       {
         "machines": [
@@ -78,6 +81,6 @@ class OpenAPI::V1::MachinesDoc < OpenAPI::V1::BaseDoc
           }
         ]
       }
-    EOS
+    MACHINES
   end
 end

app/doc/open_api/v1/reservations_doc.rb

@@ -1,3 +1,6 @@
+# frozen_string_literal: true
+
+# openAPI documentation for reservations endpoint
 class OpenAPI::V1::ReservationsDoc < OpenAPI::V1::BaseDoc
   resource_description do
     short 'Reservations'
@@ -9,14 +12,14 @@ class OpenAPI::V1::ReservationsDoc < OpenAPI::V1::BaseDoc
   include OpenAPI::V1::Concerns::ParamGroups
 
   doc_for :index do
-    api :GET, "/#{API_VERSION}/reservations", "Reservations index"
+    api :GET, "/#{API_VERSION}/reservations", 'Reservations index'
-    description "Index of reservations made by users, with optional pagination. Order by *created_at* descendant."
+    description 'Index of reservations made by users, with optional pagination. Order by *created_at* descendant.'
     param_group :pagination
-    param :user_id, [Integer, Array], optional: true, desc: "Scope the request to one or various users."
+    param :user_id, [Integer, Array], optional: true, desc: 'Scope the request to one or various users.'
-    param :reservable_type, ['Event', 'Machine', 'Training'], optional: true, desc: "Scope the request to a specific type of reservable."
+    param :reservable_type, %w[Event Machine Training], optional: true, desc: 'Scope the request to a specific type of reservable.'
-    param :reservable_id, [Integer, Array], optional: true, desc: "Scope the request to one or various reservables."
+    param :reservable_id, [Integer, Array], optional: true, desc: 'Scope the request to one or various reservables.'
 
-    example <<-EOS
+    example <<-RESERVATIONS
       # /open_api/v1/reservations?reservable_type=Event&page=1&per_page=3
       {
         "reservations": [
@@ -85,6 +88,6 @@ class OpenAPI::V1::ReservationsDoc < OpenAPI::V1::BaseDoc
           }
         ]
       }
-    EOS
+    RESERVATIONS
   end
 end

app/doc/open_api/v1/trainings_doc.rb

@@ -1,3 +1,6 @@
+# frozen_string_literal: true
+
+# openAPI documentation for trainings endpoint
 class OpenAPI::V1::TrainingsDoc < OpenAPI::V1::BaseDoc
   resource_description do
     short 'Trainings'
@@ -7,9 +10,9 @@ class OpenAPI::V1::TrainingsDoc < OpenAPI::V1::BaseDoc
   end
 
   doc_for :index do
-    api :GET, "/#{API_VERSION}/trainings", "Trainings index"
+    api :GET, "/#{API_VERSION}/trainings", 'Trainings index'
-    description "Trainings index. Order by *created_at* ascendant."
+    description 'Trainings index. Order by *created_at* ascendant.'
-    example <<-EOS
+    example <<-TRAININGS
       # /open_api/v1/trainings
       {
         "trainings": [
@@ -75,6 +78,6 @@ class OpenAPI::V1::TrainingsDoc < OpenAPI::V1::BaseDoc
           }
         ]
       }
-    EOS
+    TRAININGS
   end
 end

app/doc/open_api/v1/user_trainings_doc.rb

@@ -1,3 +1,6 @@
+# frozen_string_literal: true
+
+# openAPI documentation for user's trainings endpoint
 class OpenAPI::V1::UserTrainingsDoc < OpenAPI::V1::BaseDoc
   resource_description do
     short 'User trainings'
@@ -9,12 +12,12 @@ class OpenAPI::V1::UserTrainingsDoc < OpenAPI::V1::BaseDoc
   include OpenAPI::V1::Concerns::ParamGroups
 
   doc_for :index do
-    api :GET, "/#{API_VERSION}/user_trainings", "User trainings index"
+    api :GET, "/#{API_VERSION}/user_trainings", 'User trainings index'
-    description "Index of trainings accomplished by users, with optional pagination. Order by *created_at* descendant."
+    description 'Index of trainings accomplished by users, with optional pagination. Order by *created_at* descendant.'
     param_group :pagination
-    param :training_id, [Integer, Array], optional: true, desc: "Scope the request to one or various trainings."
+    param :training_id, [Integer, Array], optional: true, desc: 'Scope the request to one or various trainings.'
-    param :user_id, [Integer, Array], optional: true, desc: "Scope the request to one or various users."
+    param :user_id, [Integer, Array], optional: true, desc: 'Scope the request to one or various users.'
-    example <<-EOS
+    example <<-TRAININGS
       # /open_api/v1/user_trainings?training_id[]=3&training_id[]=4&page=1&per_page=2
       {
         "user_trainings": [
@@ -94,6 +97,6 @@ class OpenAPI::V1::UserTrainingsDoc < OpenAPI::V1::BaseDoc
           }
         ]
       }
-    EOS
+    TRAININGS
   end
 end

app/doc/open_api/v1/users_doc.rb

@@ -1,3 +1,6 @@
+# frozen_string_literal: true
+
+# openAPI documentation for user endpoint
 class OpenAPI::V1::UsersDoc < OpenAPI::V1::BaseDoc
   resource_description do
     short 'Users'
@@ -9,12 +12,12 @@ class OpenAPI::V1::UsersDoc < OpenAPI::V1::BaseDoc
   include OpenAPI::V1::Concerns::ParamGroups
 
   doc_for :index do
-    api :GET, "/#{API_VERSION}/users", "Users index"
+    api :GET, "/#{API_VERSION}/users", 'Users index'
-    description "Users index, with optional pagination. Order by *created_at* descendant."
+    description 'Users index, with optional pagination. Order by *created_at* descendant.'
     param_group :pagination
-    param :email, [String, Array], optional: true, desc: "Filter users by *email* using strict matching."
+    param :email, [String, Array], optional: true, desc: 'Filter users by *email* using strict matching.'
-    param :user_id, [Integer, Array], optional: true, desc: "Filter users by *id* using strict matching."
+    param :user_id, [Integer, Array], optional: true, desc: 'Filter users by *id* using strict matching.'
-    example <<-EOS
+    example <<-USERS
       # /open_api/v1/users?page=1&per_page=4
       {
         "users": [
@@ -92,6 +95,6 @@ class OpenAPI::V1::UsersDoc < OpenAPI::V1::BaseDoc
           }
         ]
       }
-    EOS
+    USERS
   end
 end