Mirror of metasploit
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

service_api_doc.rb 6.7KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229
  1. require 'swagger/blocks'
  2. module ServiceApiDoc
  3. include Swagger::Blocks
  4. HOST_DESC = 'The host where this service is running.'
  5. HOST_ID_DESC = 'The ID of the host record this service is associated with.'
  6. PORT_DESC = 'The port this service is listening on.'
  7. PORT_EXAMPLE = '443'
  8. PROTO_DESC = 'The transport layer protocol this service is using.'
  9. PROTO_ENUM = ['tcp', 'udp']
  10. NAME_DESC = 'The application layer protocol.'
  11. NAME_EXAMPLE = "'ssh', 'mssql', 'smb', etc."
  12. STATE_DESC = 'The current listening state of the service.'
  13. STATE_ENUM = ['open', 'closed', 'filtered', 'unknown']
  14. INFO_DESC = 'Detailed information about the service such as name and version information.'
  15. INFO_EXAMPLE = "'ProFTPD 1.3.5', 'WEBrick httpd 1.3.1 Ruby 2.3.4', etc."
  16. # Swagger documentation for Service model
  17. swagger_schema :Service do
  18. key :required, [:id, :port, :proto]
  19. property :id, type: :integer, format: :int32, description: RootApiDoc::ID_DESC
  20. property :host_id, type: :integer, format: :int32, description: HOST_ID_DESC
  21. property :port, type: :string, description: PORT_DESC, example: PORT_EXAMPLE
  22. property :proto, type: :string, description: PROTO_DESC, enum: PROTO_ENUM
  23. property :name, type: :string, description: NAME_DESC, example: NAME_EXAMPLE
  24. property :info, type: :string, description: INFO_DESC, example: INFO_EXAMPLE
  25. property :state, type: :string, description: STATE_DESC, enum: STATE_ENUM
  26. property :created_at, type: :string, format: :date_time, description: RootApiDoc::CREATED_AT_DESC
  27. property :updated_at, type: :string, format: :date_time, description: RootApiDoc::UPDATED_AT_DESC
  28. end
  29. swagger_path '/api/v1/services' do
  30. # Swagger documentation for /api/v1/services GET
  31. operation :get do
  32. key :description, 'Return services that are stored in the database.'
  33. key :tags, [ 'service' ]
  34. parameter :workspace
  35. response 200 do
  36. key :description, 'Returns service data.'
  37. schema do
  38. property :data do
  39. key :type, :array
  40. items do
  41. key :'$ref', :Service
  42. end
  43. end
  44. end
  45. end
  46. response 401 do
  47. key :description, RootApiDoc::DEFAULT_RESPONSE_401
  48. schema do
  49. key :'$ref', :AuthErrorModel
  50. end
  51. end
  52. response 500 do
  53. key :description, RootApiDoc::DEFAULT_RESPONSE_500
  54. schema do
  55. key :'$ref', :ErrorModel
  56. end
  57. end
  58. end
  59. # Swagger documentation for /api/v1/services POST
  60. operation :post do
  61. key :description, 'Create a Service.'
  62. key :tags, [ 'service' ]
  63. parameter do
  64. key :in, :body
  65. key :name, :body
  66. key :description, 'The attributes to assign to the service.'
  67. key :required, true
  68. schema do
  69. property :workspace, type: :string, required: true, description: RootApiDoc::WORKSPACE_POST_DESC, example: RootApiDoc::WORKSPACE_POST_EXAMPLE
  70. property :host, type: :string, format: :ipv4, required: true, description: HOST_DESC, example: RootApiDoc::HOST_EXAMPLE
  71. property :port, type: :string, required: true, description: PORT_DESC, example: PORT_EXAMPLE
  72. property :proto, type: :string, required: true, description: PROTO_DESC, enum: PROTO_ENUM
  73. property :name, type: :string, description: NAME_DESC, example: NAME_EXAMPLE
  74. property :info, type: :string, description: INFO_DESC, example: INFO_EXAMPLE
  75. property :state, type: :string, description: STATE_DESC, enum: STATE_ENUM
  76. end
  77. end
  78. response 200 do
  79. key :description, RootApiDoc::DEFAULT_RESPONSE_200
  80. schema do
  81. property :data do
  82. key :'$ref', :Service
  83. end
  84. end
  85. end
  86. response 401 do
  87. key :description, RootApiDoc::DEFAULT_RESPONSE_401
  88. schema do
  89. key :'$ref', :AuthErrorModel
  90. end
  91. end
  92. response 500 do
  93. key :description, RootApiDoc::DEFAULT_RESPONSE_500
  94. schema do
  95. key :'$ref', :ErrorModel
  96. end
  97. end
  98. end
  99. # Swagger documentation for /api/v1/services/ DELETE
  100. operation :delete do
  101. key :description, 'Delete the specified services.'
  102. key :tags, [ 'service' ]
  103. parameter :delete_opts
  104. response 200 do
  105. key :description, 'Returns an array containing the successfully deleted services.'
  106. schema do
  107. property :data do
  108. key :type, :array
  109. items do
  110. key :'$ref', :Service
  111. end
  112. end
  113. end
  114. end
  115. response 401 do
  116. key :description, RootApiDoc::DEFAULT_RESPONSE_401
  117. schema do
  118. key :'$ref', :AuthErrorModel
  119. end
  120. end
  121. response 500 do
  122. key :description, RootApiDoc::DEFAULT_RESPONSE_500
  123. schema do
  124. key :'$ref', :ErrorModel
  125. end
  126. end
  127. end
  128. end
  129. swagger_path '/api/v1/services/{id}' do
  130. # Swagger documentation for api/v1/services/:id GET
  131. operation :get do
  132. key :description, 'Return specific service that is stored in the database.'
  133. key :tags, [ 'service' ]
  134. parameter do
  135. key :name, :id
  136. key :in, :path
  137. key :description, 'ID of service to retrieve.'
  138. key :required, true
  139. key :type, :integer
  140. key :format, :int32
  141. end
  142. response 200 do
  143. key :description, 'Returns service data.'
  144. schema do
  145. property :data do
  146. key :'$ref', :Service
  147. end
  148. end
  149. end
  150. response 401 do
  151. key :description, RootApiDoc::DEFAULT_RESPONSE_401
  152. schema do
  153. key :'$ref', :AuthErrorModel
  154. end
  155. end
  156. response 500 do
  157. key :description, RootApiDoc::DEFAULT_RESPONSE_500
  158. schema do
  159. key :'$ref', :ErrorModel
  160. end
  161. end
  162. end
  163. # Swagger documentation for /api/v1/services/:id PUT
  164. operation :put do
  165. key :description, 'Update the attributes on an existing service.'
  166. key :tags, [ 'service' ]
  167. parameter :update_id
  168. parameter do
  169. key :in, :body
  170. key :name, :body
  171. key :description, 'The updated attributes to overwrite to the service.'
  172. key :required, true
  173. schema do
  174. key :'$ref', :Service
  175. end
  176. end
  177. response 200 do
  178. key :description, RootApiDoc::DEFAULT_RESPONSE_200
  179. schema do
  180. property :data do
  181. key :'$ref', :Service
  182. end
  183. end
  184. end
  185. response 401 do
  186. key :description, RootApiDoc::DEFAULT_RESPONSE_401
  187. schema do
  188. key :'$ref', :AuthErrorModel
  189. end
  190. end
  191. response 500 do
  192. key :description, RootApiDoc::DEFAULT_RESPONSE_500
  193. schema do
  194. key :'$ref', :ErrorModel
  195. end
  196. end
  197. end
  198. end
  199. end