Add doc for user operations

documentation/api/v1/auth_api_doc.rb

@@ -15,7 +15,7 @@ module AuthApiDoc
   end
 
   swagger_path '/api/v1/auth/generate-token' do
-    # Swagger documentation for /api/v1/auth/generate-tokenGET
+    # Swagger documentation for /api/v1/auth/generate-token GET
     operation :get do
 
       key :description, 'Return a valid Authorization Bearer token.'

documentation/api/v1/root_api_doc.rb

@@ -63,6 +63,7 @@ module RootApiDoc
     tag name: 'service', description: 'Service operations.'
     tag name: 'session', description: 'Session operations.'
     tag name: 'session_event', description: 'Session Event operations.'
+    tag name: 'user', description: 'User operations.'
     tag name: 'vuln', description: 'Vuln operations.'
     tag name: 'vuln_attempt', description: 'Vuln Attempt operations.'
     tag name: 'workspace', description: 'Workspace operations.'

documentation/api/v1/user_api_doc.rb

@@ -0,0 +1,113 @@
+require 'swagger/blocks'
+
+module UserApiDoc
+  include Swagger::Blocks
+
+  USERNAME_DESC = 'The username of the user.'
+  PASSWORD_DESC = 'The password of the user.'
+  CRYPTED_PASSWORD_DESC = 'The encrypted password of the user.'
+  CRYPTED_PASSWORD_EXAMPLE = '$2a$10$ZOmd0VVkcVLTKW/0Cw0BMeqVITeVN4tPQvRvwBizNyM1NIz45oxda'
+  PASSWORD_SALT_DESC = 'The password salt for the user\'s password.'
+  PERSISTENCE_TOKEN_DESC = 'The persistence token for the user.'
+  PERSISTENCE_TOKEN_EXAMPLE = '1a6347561b72aff163b4c1b8324cfdf9ccca37caa681e29d348677afe0cb56927e2e3ab4dc612723'
+  FULLNAME_DESC = 'The user\'s full name.'
+  FULLNAME_EXAMPLE = 'Bullwinkle J. Moose'
+  EMAIL_DESC = 'The user\'s email address.'
+  EMAIL_EXAMPLE = 'bullwinkle_moose@rapid7.com'
+  PHONE_DESC = 'The user\'s phone number.'
+  PHONE_EXAMPLE = '555-555-5555'
+  COMPANY_DESC = 'The user\'s company.'
+  COMPANY_EXAMPLE = 'Rapid7'
+  PREFS_DESC = 'The user\'s preferences.'
+  PREFS_EXAMPLE = {}
+  ADMIN_DESC = 'A boolean indicating whether the user is an admin.'
+  ADMIN_EXAMPLE = false
+
+
+# Swagger documentation for User model
+  swagger_schema :User do
+    key :required, [:username, :password]
+    property :id, type: :integer, format: :int32, description: RootApiDoc::ID_DESC
+    property :username, type: :string, description: USERNAME_DESC
+    property :crypted_password, type: :string, description: CRYPTED_PASSWORD_DESC, example: CRYPTED_PASSWORD_EXAMPLE
+    property :password_salt, type: :string, description: PASSWORD_SALT_DESC
+    property :persistence_token, type: :string, description: PERSISTENCE_TOKEN_DESC, example: PERSISTENCE_TOKEN_EXAMPLE
+    property :created_at, type: :string, description: RootApiDoc::CREATED_AT_DESC
+    property :updated_at, type: :string, description: RootApiDoc::UPDATED_AT_DESC
+    property :fullname, type: :string, description: FULLNAME_DESC, example: FULLNAME_EXAMPLE
+    property :email, type: :string, description: EMAIL_DESC, example: EMAIL_EXAMPLE
+    property :phone, type: :string, description: PHONE_DESC, example: PHONE_EXAMPLE
+    property :company, type: :string, description: COMPANY_DESC, example: COMPANY_EXAMPLE
+    property :prefs, type: :string, description: PREFS_DESC, example: PREFS_EXAMPLE
+    property :admin, type: :string, description: ADMIN_DESC, example: ADMIN_EXAMPLE
+  end
+
+  swagger_path '/api/v1/users' do
+    # Swagger documentation for /api/v1/users GET
+    operation :get do
+      key :description, 'Return users that are stored in the database.'
+      key :tags, [ 'user' ]
+
+      response 200 do
+        key :description, 'Returns user data.'
+        schema do
+          property :data do
+            key :type, :array
+            items do
+              key :'$ref', :User
+            end
+          end
+        end
+      end
+
+      response 500 do
+        key :description, 'An error occurred during the operation. See the message for more details.'
+        schema do
+          key :'$ref', :ErrorModel
+        end
+      end
+    end
+
+    # Swagger documentation for /api/v1/users GET
+    operation :post do
+      key :description, 'Create a user.'
+      key :tags, [ 'user' ]
+
+      parameter do
+        key :in, :body
+        key :name, :body
+        key :description, 'The attributes to assign to the user.'
+        key :required, true
+        schema do
+          property :username, type: :string, required: true, description: USERNAME_DESC
+          property :password, type: :string, required: true, description: PASSWORD_DESC
+          property :fullname, type: :string, description: FULLNAME_DESC, example: FULLNAME_EXAMPLE
+          property :email, type: :string, description: EMAIL_DESC, example: EMAIL_EXAMPLE
+          property :phone, type: :string, description: PHONE_DESC, example: PHONE_EXAMPLE
+          property :company, type: :string, description: COMPANY_DESC, example: COMPANY_EXAMPLE
+          property :prefs, type: :string, description: PREFS_DESC, example: PREFS_EXAMPLE
+        end
+      end
+
+      response 200 do
+        key :description, 'Successful operation.'
+        schema do
+          property :data do
+            key :type, :array
+            items do
+              key :'$ref', :User
+            end
+          end
+        end
+      end
+
+      response 500 do
+        key :description, 'An error occurred during the operation. See the message for more details.'
+        schema do
+          key :'$ref', :ErrorModel
+        end
+      end
+
+    end
+  end
+end

lib/msf/core/db_manager/http/servlet/api_docs_servlet.rb

@@ -15,6 +15,7 @@ load 'documentation/api/v1/note_api_doc.rb'
 load 'documentation/api/v1/service_api_doc.rb'
 load 'documentation/api/v1/session_api_doc.rb'
 load 'documentation/api/v1/session_event_api_doc.rb'
+load 'documentation/api/v1/user_api_doc.rb'
 load 'documentation/api/v1/vuln_api_doc.rb'
 load 'documentation/api/v1/vuln_attempt_api_doc.rb'
 load 'documentation/api/v1/workspace_api_doc.rb'
@@ -59,6 +60,7 @@ module ApiDocsServlet
           ServiceApiDoc,
           SessionApiDoc,
           SessionEventApiDoc,
+          UserApiDoc,
           VulnApiDoc,
           VulnAttemptApiDoc,
           WorkspaceApiDoc