From 9c93a62b97eaead7ca085c5ff4ce6eb6f3d41408 Mon Sep 17 00:00:00 2001
From: Dan Ungureanu <dan@ungureanu.me>
Date: Thu, 11 Mar 2021 18:19:32 +0200
Subject: [PATCH] DEV: Update API documentation for invites (#12360)

---
 app/controllers/invites_controller.rb |  1 -
 app/models/invite.rb                  |  2 +-
 app/serializers/invite_serializer.rb  | 15 ++++++++++++++-
 spec/requests/api/invites_spec.rb     | 27 +++++++++++++++++++++------
 4 files changed, 36 insertions(+), 9 deletions(-)

diff --git a/app/controllers/invites_controller.rb b/app/controllers/invites_controller.rb
index 9cb6c02a511..9804308c4d1 100644
--- a/app/controllers/invites_controller.rb
+++ b/app/controllers/invites_controller.rb
@@ -57,7 +57,6 @@ class InvitesController < ApplicationController
 
     begin
       invite = Invite.generate(current_user,
-        invite_key: params[:invite_key],
         email: params[:email],
         skip_email: params[:skip_email],
         invited_by: current_user,
diff --git a/app/models/invite.rb b/app/models/invite.rb
index 7aa89062d54..ed5638b2186 100644
--- a/app/models/invite.rb
+++ b/app/models/invite.rb
@@ -133,7 +133,7 @@ class Invite < ActiveRecord::Base
         emailed_status: emailed_status
       )
     else
-      create_args = opts.slice(:invite_key, :email, :moderator, :custom_message, :max_redemptions_allowed)
+      create_args = opts.slice(:email, :moderator, :custom_message, :max_redemptions_allowed)
       create_args[:invited_by] = invited_by
       create_args[:email] = email
       create_args[:emailed_status] = emailed_status
diff --git a/app/serializers/invite_serializer.rb b/app/serializers/invite_serializer.rb
index 4e9a0fae8f9..c09ec9f5740 100644
--- a/app/serializers/invite_serializer.rb
+++ b/app/serializers/invite_serializer.rb
@@ -5,9 +5,10 @@ class InviteSerializer < ApplicationSerializer
              :link,
              :email,
              :emailed,
-             :redemption_count,
              :max_redemptions_allowed,
+             :redemption_count,
              :custom_message,
+             :created_at,
              :updated_at,
              :expires_at,
              :expired
@@ -27,6 +28,18 @@ class InviteSerializer < ApplicationSerializer
     object.emailed_status != Invite.emailed_status_types[:not_required]
   end
 
+  def include_custom_message?
+    email.present?
+  end
+
+  def include_max_redemptions_allowed?
+    email.blank?
+  end
+
+  def include_redemption_count?
+    email.blank?
+  end
+
   def expired
     object.expired?
   end
diff --git a/spec/requests/api/invites_spec.rb b/spec/requests/api/invites_spec.rb
index 5084ae7f0c1..cace13aa162 100644
--- a/spec/requests/api/invites_spec.rb
+++ b/spec/requests/api/invites_spec.rb
@@ -7,7 +7,7 @@ describe 'invites' do
   let(:'Api-Username') { 'system' }
 
   path '/invites.json' do
-    post 'Invite to site by email' do
+    post 'Create an invite' do
       tags 'Invites'
       consumes 'application/json'
       parameter name: 'Api-Key', in: :header, type: :string, required: true
@@ -16,16 +16,31 @@ describe 'invites' do
       parameter name: :request_body, in: :body, schema: {
         type: :object,
         properties: {
-          email: { type: :string },
-          group_names: { type: :string },
-          custom_message: { type: :string },
-        }, required: ['email']
+          email: { type: :string, example: "not-a-user-yet@example.com", description: "required for email invites only" },
+          skip_email: { type: :boolean, default: false },
+          custom_message: { type: :string, description: "optional, for email invites" },
+          max_redemptions_allowed: { type: :integer, example: 5, default: 1, description: "optional, for link invites" },
+          topic_id: { type: :int },
+          group_id: { type: [:int], description: "optional, either this or `group_names`" },
+          group_names: { type: :string, description: "optional, either this or `group_id`" },
+          expires_at: { type: :string, default: "controlled by invite_expiry_days site setting" },
+        }
       }
 
       produces 'application/json'
       response '200', 'success response' do
         schema type: :object, properties: {
-          success: { type: :string, example: "OK" }
+          id: { type: :integer, example: 42 },
+          link: { type: :string, example: "http://example.com/invites/9045fd767efe201ca60c6658bcf14158" },
+          email: { type: :string, example: "not-a-user-yet@example.com" },
+          emailed: { type: :boolean, example: false },
+          custom_message: { type: :string, example: "Hello world!", nullable: true },
+          topics: { type: :array, example: [] },
+          groups: { type: :array, example: [] },
+          created_at: { type: :string, example: "2021-01-01T12:00:00.000Z" },
+          updated_at: { type: :string, example: "2021-01-01T12:00:00.000Z" },
+          expires_at: { type: :string, example: "2021-02-01T12:00:00.000Z" },
+          expired: { type: :boolean, example: false },
         }
 
         let(:request_body) { { email: 'not-a-user-yet@example.com' } }