From a850568a52d2fd520837c28c15fcd176717f2f86 Mon Sep 17 00:00:00 2001
From: Blake Erickson <o.blakeerickson@gmail.com>
Date: Fri, 7 Jan 2022 16:09:32 -0700
Subject: [PATCH] DEV: Document delete post API endpoint (#15495)

Adding a spec for documenting the delete post API endpoint for our api
docs. As part of this added detailed info for the `force_destroy`
parameter for permanently deleting a post.
---
 spec/requests/api/posts_spec.rb               | 25 +++++++++++++++++++
 .../api/schemas/json/post_delete_request.json | 11 ++++++++
 2 files changed, 36 insertions(+)
 create mode 100644 spec/requests/api/schemas/json/post_delete_request.json

diff --git a/spec/requests/api/posts_spec.rb b/spec/requests/api/posts_spec.rb
index 0456643e339..a3934282989 100644
--- a/spec/requests/api/posts_spec.rb
+++ b/spec/requests/api/posts_spec.rb
@@ -291,6 +291,31 @@ describe 'posts' do
         end
       end
     end
+
+    delete 'delete a single post' do
+      tags 'Posts'
+      operationId 'deletePost'
+      consumes 'application/json'
+      expected_request_schema = load_spec_schema('post_delete_request')
+      parameter name: :id, in: :path, schema: { type: :integer }
+      parameter name: :params, in: :body, schema: expected_request_schema
+
+      produces 'application/json'
+      response '200', 'success response' do
+        expected_response_schema = nil
+        schema expected_response_schema
+
+        let(:topic) { Fabricate(:topic) }
+        let(:post) { Fabricate(:post, topic_id: topic.id, post_number: 3) }
+        let(:id) { post.id }
+        let(:params) { { 'force_destroy' => false } }
+
+        it_behaves_like "a JSON endpoint", 200 do
+          let(:expected_response_schema) { expected_response_schema }
+          let(:expected_request_schema) { expected_request_schema }
+        end
+      end
+    end
   end
 
   path '/posts/{id}/locked.json' do
diff --git a/spec/requests/api/schemas/json/post_delete_request.json b/spec/requests/api/schemas/json/post_delete_request.json
new file mode 100644
index 00000000000..11ef75272f3
--- /dev/null
+++ b/spec/requests/api/schemas/json/post_delete_request.json
@@ -0,0 +1,11 @@
+{
+  "additionalProperties": false,
+  "properties": {
+    "force_destroy": {
+      "type": "boolean",
+      "example": true,
+      "description": "The `SiteSetting.can_permanently_delete` needs to be enabled first before this param can be used. Also this endpoint needs to be called first without `force_destroy` and then followed up with a second call 5 minutes later with `force_destroy` to permanently delete."
+
+    }
+  }
+}