(doc) Updated OpenAPI documentation

CHANGELOG.md

@@ -3,6 +3,7 @@
 - Optional external identifier for users
 - Accounting data is now built each night and saved in database
 - OpenAPI endpoint to fetch accounting data
+- Updated OpenAPI documentation
 - Fix a bug: providing an array of attributes to filter OpenApi data, results in error
 - Fix a bug: unable to manage stocks on new products
 - Updated react-modal to 3.16.1

app/controllers/open_api/v1/bookable_machines_controller.rb

@@ -9,9 +9,7 @@ class OpenAPI::V1::BookableMachinesController < OpenAPI::V1::BaseController
     raise ActionController::ParameterMissing if params[:user_id].blank?
 
     @machines = Machine.all
-
     @machines = @machines.where(id: params[:machine_id]) if params[:machine_id].present?
-
     @machines = @machines.to_a
 
     user = User.find(params[:user_id])
@@ -20,15 +18,11 @@ class OpenAPI::V1::BookableMachinesController < OpenAPI::V1::BaseController
       (machine.trainings.count != 0) and !user.training_machine?(machine)
     end
 
-
-    @hours_remaining = Hash[@machines.map { |m| [m.id, 0] }]
-
-
+    @hours_remaining = @machines.to_h { |m| [m.id, 0] }
 
     return unless user.subscription
 
     plan_id = user.subscription.plan_id
-
     @machines.each do |machine|
       credit = Credit.find_by(plan_id: plan_id, creditable: machine)
       users_credit = user.users_credits.find_by(credit: credit) if credit

app/doc/open_api/v1/bookable_machines_doc.rb

@@ -11,8 +11,10 @@ class OpenAPI::V1::BookableMachinesDoc < OpenAPI::V1::BaseDoc
 
   doc_for :index do
     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. If the given user has machine credits due to his current subscription, ' \
+                'it will be reported in *hours_remaining*.'
     param :user_id, Integer, required: true, desc: 'Id of the given user.'
+    param :machine_id, Integer, optional: true, desc: 'Id of a machine to filter by'
     example <<-MACHINES
       # /open_api/v1/bookable_machines?user_id=522
       {
@@ -44,7 +46,7 @@ class OpenAPI::V1::BookableMachinesDoc < OpenAPI::V1::BaseDoc
             "updated_at": "2014-06-30T15:10:14.272+02:00",
             "created_at": "2014-06-30T03:32:31.977+02:00",
             "description": "La découpeuse Vinyle, Roland CAMM ...",
-            "spec": "Largeurs de support acceptées: de 50 mm à 70 ... 50 cm/sec ... mécanique: 0,0125 mm/pas\r\n",
+            "spec": "Largeurs de support acceptées: de 50 mm à 70 ... 50 cm/sec ... mécanique: 0,0125 mm/pas",
             "hours_remaining": 0
           },
           {

app/views/open_api/v1/bookable_machines/index.json.jbuilder

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 json.machines @machines do |machine|
   json.partial! 'open_api/v1/machines/machine', machine: machine
   json.extract! machine, :description, :spec

config/initializers/apipie.rb

@@ -12,7 +12,8 @@ Apipie.configure do |config|
   config.app_info['v1'] = <<-RDOC
     = Pagination
     ---
-    Pagination is done using headers. Following RFC-5988 standard for web linking.
+    You can ask for pagination on your requests, by providing the GET parameters *page* and *per_page* (when it's available).
+    The meta-data about pagination will be returned in the headers, following RFC-5988 standard for web linking.
     It uses headers *Link*, *Total* and *Per-Page*.
 
     = Authentication

test/integration/open_api/bookable_machines_test.rb

@@ -18,4 +18,9 @@ class OpenApi::BookableMachinesTest < ActionDispatch::IntegrationTest
     get '/open_api/v1/bookable_machines?user_id=3', headers: open_api_headers(@token)
     assert_response :success
   end
+
+  test 'check if a given machine is bookable by user' do
+    get '/open_api/v1/bookable_machines?user_id=3&machine_id=1', headers: open_api_headers(@token)
+    assert_response :success
+  end
 end