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
+  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
+      # /open_api/v1/invoices/2809/download
-      EOS
+    URL
-    end
+  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": [
@@ -63,7 +66,7 @@ class OpenAPI::V1::MachinesDoc < OpenAPI::V1::BaseDoc
             "description": "La fraiseuse numérique Roland Modela MDX-20\r\n\r\nInformations générales :\r\nCette machine est utilisée  pour l'usinage et le scannage 3D de précision. Elle permet principalement d'usiner des circuits imprimés et des moules de petite taille. Le faible diamètre des fraises utilisées (Ø 0,3 mm à  Ø 6mm) implique que certains temps d'usinages peuvent êtres long (> 12h), c'est pourquoi cette fraiseuse peut être laissée en autonomie toute une nuit afin d'obtenir le plus précis des usinages au FabLab.\r\n\r\nMatériaux usinables :\r\nLes principaux matériaux usinables sont : bois, plâtre, résine, cire usinable, cuivre.\r\n",
             "spec": "Taille du plateau X/Y : 220 mm x 160 mm\r\nVolume maximal de travail: 203,2 mm (X), 152,4 mm (Y), 60,5 mm (Z)\r\nPrécision usinage: 0,00625 mm\r\nPrécision scannage: réglable de 0,05 à 5 mm (axes X,Y) et 0,025 mm (axe Z)\r\nVitesse d'analyse (scannage): 4-15 mm/sec\r\n \r\n \r\nLogiciel utilisé pour le fraisage: Roland Modela player 4 \r\nLogiciel utilisé pour l'usinage de circuits imprimés: Cad.py (linux)\r\nFormats acceptés: STL,PNG 3D\r\nFormat d'exportation des données scannées: DXF, VRML, STL, 3DMF, IGES, Grayscale, Point Group et BMP\r\n"
           },
-          # 
+          #
           # ....
           #
           {
@@ -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