rooty/fab-manager
1
0
Fork 0
mirror of https://github.com/LaCasemate/fab-manager.git synced 2024-11-28 09:24:24 +01:00
Code Issues Releases Activity

apply coding rules to openAPI doc

Browse Source
This commit is contained in:
Sylvain 2019-03-26 14:27:39 +01:00
parent b31bb272cc
commit fcc78d3930
12 changed files with 87 additions and 75 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
app/doc/open_api/api_doc.rb
View File

@ -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.

3
app/doc/open_api/application_doc.rb
View File

@ -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

7
app/doc/open_api/v1/base_doc.rb
View File

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

13
app/doc/open_api/v1/bookable_machines_doc.rb
View File

@ -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"
description "Machines that a given user is allowed to book."
param :user_id, Integer, required: true, desc: "Id of the given user."
example <<-EOS
api :GET, "/#{API_VERSION}/bookable_machines", 'Bookable machines index'
description 'Machines that a given user is allowed to book.'
param :user_id, Integer, required: true, desc: 'Id of the given user.'
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

25
app/doc/open_api/v1/concerns/param_groups.rb
View File

@ -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

15
app/doc/open_api/v1/events_doc.rb
View File

@ -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 :upcoming, [FalseClass, TrueClass], optional: true, desc: "Scope for the upcoming events."
description "Events index. Order by *created_at* desc."
example <<-EOS
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.'
description 'Events index. Order by *created_at* desc.'
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

25
app/doc/open_api/v1/invoices_doc.rb
View File

@ -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."
example <<-EOS
param :user_id, [Integer, Array], optional: true, desc: 'Scope the request to one or various users.'
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"
param :id, Integer, desc: "Invoice id", required: true
doc_for :download do
api :GET, "/#{API_VERSION}/invoices/:id/download", 'Download an invoice'
param :id, Integer, desc: 'Invoice id', required: true
example <<-EOS
# /open_api/v1/invoices/2809/download
EOS
end
example <<-URL
# /open_api/v1/invoices/2809/download
URL
end
end

13
app/doc/open_api/v1/machines_doc.rb
View File

@ -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"
description "Machines index. Order by *created_at* ascendant."
example <<-EOS
api :GET, "/#{API_VERSION}/machines", 'Machines index'
description 'Machines index. Order by *created_at* ascendant.'
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

17
app/doc/open_api/v1/reservations_doc.rb
View File

@ -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"
description "Index of reservations made by users, with optional pagination. Order by *created_at* descendant."
api :GET, "/#{API_VERSION}/reservations", 'Reservations index'
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 :reservable_type, ['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 :user_id, [Integer, Array], optional: true, desc: 'Scope the request to one or various users.'
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.'
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

11
app/doc/open_api/v1/trainings_doc.rb
View File

@ -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"
description "Trainings index. Order by *created_at* ascendant."
example <<-EOS
api :GET, "/#{API_VERSION}/trainings", 'Trainings index'
description 'Trainings index. Order by *created_at* ascendant.'
example <<-TRAININGS
# /open_api/v1/trainings
{
"trainings": [
@ -75,6 +78,6 @@ class OpenAPI::V1::TrainingsDoc < OpenAPI::V1::BaseDoc
}
]
}
EOS
TRAININGS
end
end

15
app/doc/open_api/v1/user_trainings_doc.rb
View File

@ -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"
description "Index of trainings accomplished by users, with optional pagination. Order by *created_at* descendant."
api :GET, "/#{API_VERSION}/user_trainings", 'User trainings index'
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 :user_id, [Integer, Array], optional: true, desc: "Scope the request to one or various users."
example <<-EOS
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.'
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

15
app/doc/open_api/v1/users_doc.rb
View File

@ -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"
description "Users index, with optional pagination. Order by *created_at* descendant."
api :GET, "/#{API_VERSION}/users", 'Users index'
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 :user_id, [Integer, Array], optional: true, desc: "Filter users by *id* using strict matching."
example <<-EOS
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.'
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