From c9515ede2e83caf58ad23ff38c94a7b292d34b85 Mon Sep 17 00:00:00 2001
From: Blake Erickson <o.blakeerickson@gmail.com>
Date: Mon, 26 Oct 2020 08:55:22 -0600
Subject: [PATCH] DEV: Add api docs for invite and group update endpoint
 (#11019)

Documenting a few more endpoints so that our api docs can be
automatically generated. Made a couple other minor changes, like
including the "OK" example for our default success response.
---
 spec/requests/api/groups_spec.rb  | 40 +++++++++++++++++---
 spec/requests/api/invites_spec.rb | 63 +++++++++++++++++++++++++++++++
 spec/requests/api/topics_spec.rb  | 10 ++---
 3 files changed, 103 insertions(+), 10 deletions(-)
 create mode 100644 spec/requests/api/invites_spec.rb

diff --git a/spec/requests/api/groups_spec.rb b/spec/requests/api/groups_spec.rb
index ab3112aa894..b5c28bfd7ed 100644
--- a/spec/requests/api/groups_spec.rb
+++ b/spec/requests/api/groups_spec.rb
@@ -11,9 +11,8 @@ describe 'groups' do
   end
 
   path '/admin/groups.json' do
-
     post 'Creates a group' do
-      tags 'Group'
+      tags 'Groups'
       consumes 'application/json'
       parameter name: :group, in: :body, schema: {
         type: :object,
@@ -22,9 +21,9 @@ describe 'groups' do
             type: :object,
             properties: {
               name: { type: :string },
-            }, required: [ 'name' ]
+            }, required: ['name']
           }
-        },
+        }, required: ['group']
       }
 
       produces 'application/json'
@@ -74,6 +73,37 @@ describe 'groups' do
         end
       end
     end
-
   end
+
+  path '/groups/{id}.json' do
+    put 'Update a group' do
+      tags 'Groups'
+      consumes 'application/json'
+      parameter name: :id, in: :path, schema: { type: :string }
+      parameter name: :group, in: :body, schema: {
+        type: :object,
+        properties: {
+          group: {
+            type: :object,
+            properties: {
+              name: { type: :string },
+            }, required: ['name']
+          }
+        }, required: ['group']
+      }
+
+      produces 'application/json'
+      response '200', 'success response' do
+        schema type: :object, properties: {
+          success: { type: :string, example: "OK" }
+        }
+
+        let(:id) { Fabricate(:group).id }
+        let(:group) { { name: 'awesome' } }
+
+        run_test!
+      end
+    end
+  end
+
 end
diff --git a/spec/requests/api/invites_spec.rb b/spec/requests/api/invites_spec.rb
new file mode 100644
index 00000000000..bf2b18f3c90
--- /dev/null
+++ b/spec/requests/api/invites_spec.rb
@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+require 'swagger_helper'
+
+describe 'invites' do
+
+  let(:'Api-Key') { Fabricate(:api_key).key }
+  let(:'Api-Username') { 'system' }
+
+  path '/invites.json' do
+    post 'Invite to site by email' do
+      tags 'Invites'
+      consumes 'application/json'
+      parameter name: 'Api-Key', in: :header, type: :string, required: true
+      parameter name: 'Api-Username', in: :header, type: :string, required: true
+
+      parameter name: :request_body, in: :body, schema: {
+        type: :object,
+        properties: {
+          email: { type: :string },
+          group_names: { type: :string },
+          custom_message: { type: :string },
+        }, required: ['email']
+      }
+
+      produces 'application/json'
+      response '200', 'success response' do
+        schema type: :object, properties: {
+          success: { type: :string, example: "OK" }
+        }
+
+        let(:request_body) { { email: 'not-a-user-yet@example.com' } }
+        run_test!
+      end
+    end
+  end
+
+  path '/invites/link.json' do
+    post 'Generate an invite link, but do not send an email' do
+      tags 'Invites'
+      consumes 'application/json'
+      parameter name: 'Api-Key', in: :header, type: :string, required: true
+      parameter name: 'Api-Username', in: :header, type: :string, required: true
+
+      parameter name: :request_body, in: :body, schema: {
+        type: :object,
+        properties: {
+          email: { type: :string },
+          group_names: { type: :string },
+          custom_message: { type: :string },
+        }, required: ['email']
+      }
+
+      produces 'application/json'
+      response '200', 'success response' do
+        schema type: :string, example: "http://discourse.example.com/invites/token_value"
+
+        let(:request_body) { { email: 'not-a-user-yet@example.com' } }
+        run_test!
+      end
+    end
+  end
+
+end
diff --git a/spec/requests/api/topics_spec.rb b/spec/requests/api/topics_spec.rb
index bd3d5f280a6..22a0b64b5ec 100644
--- a/spec/requests/api/topics_spec.rb
+++ b/spec/requests/api/topics_spec.rb
@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 require 'swagger_helper'
 
-describe 'posts' do
+describe 'topics' do
 
   let(:'Api-Key') { Fabricate(:api_key).key }
   let(:'Api-Username') { 'system' }
@@ -526,7 +526,7 @@ describe 'posts' do
       produces 'application/json'
       response '200', 'topic updated' do
         schema type: :object, properties: {
-          success: { type: :string },
+          success: { type: :string, example: "OK" },
           topic_status_update: { type: :string, nullable: true },
         }
 
@@ -872,7 +872,7 @@ describe 'posts' do
       produces 'application/json'
       response '200', 'topic updated' do
         schema type: :object, properties: {
-          success: { type: :string },
+          success: { type: :string, example: "OK" }
         }
 
         let(:request_body) { { notification_level: '3' } }
@@ -904,7 +904,7 @@ describe 'posts' do
       produces 'application/json'
       response '200', 'topic updated' do
         schema type: :object, properties: {
-          success: { type: :string },
+          success: { type: :string, example: "OK" }
         }
 
         let(:request_body) { { timestamp: '1594291380' } }
@@ -946,7 +946,7 @@ describe 'posts' do
       produces 'application/json'
       response '200', 'topic updated' do
         schema type: :object, properties: {
-          success: { type: :string },
+          success: { type: :string, example: "OK" },
           execute_at: { type: :string },
           duration: { type: :string, nullable: true },
           based_on_last_post: { type: :boolean },