DEV: Document some of the badge api endpoints (#13919)

DEV: Document some of the badge api endpoints (#13919)

Adding some api documentation for the badge routes.

diff --git a/spec/requests/api/badges_spec.rb b/spec/requests/api/badges_spec.rb
new file mode 100644
index 0000000..92a8ad5
--- /dev/null
+++ b/spec/requests/api/badges_spec.rb
@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+require 'swagger_helper'
+
+describe 'badges' do
+
+  let(:admin) { Fabricate(:admin) }
+  let(:badge) { Fabricate(:badge) }
+
+  before do
+    Jobs.run_immediately!
+    sign_in(admin)
+  end
+
+  path '/admin/badges.json' do
+
+    get 'List badges' do
+      tags 'Badges'
+      consumes 'application/json'
+      expected_request_schema = nil
+
+      produces 'application/json'
+      response '200', 'success response' do
+        expected_response_schema = load_spec_schema('badge_list_response')
+        schema expected_response_schema
+
+        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
+
+    post 'Create badge' do
+      tags 'Badges'
+      consumes 'application/json'
+      expected_request_schema = load_spec_schema('badge_create_request')
+      parameter name: :params, in: :body, schema: expected_request_schema
+
+      produces 'application/json'
+      response '200', 'success response' do
+        expected_response_schema = load_spec_schema('badge_create_response')
+        schema expected_response_schema
+
+        let(:params) { {
+          'name' => 'badge1',
+          'badge_type_id' => 2
+        } }
+
+        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 '/admin/badges/{id}.json' do
+
+    put 'Update badge' do
+      tags 'Badges'
+      consumes 'application/json'
+      expected_request_schema = load_spec_schema('badge_update_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 = load_spec_schema('badge_update_response')
+        schema expected_response_schema
+
+        let(:id) { badge.id }
+
+        let(:params) { {
+          'name' => 'badge1',
+          'badge_type_id' => 2
+        } }
+
+        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
+
+    delete 'Delete badge' do
+      tags 'Badges'
+      consumes 'application/json'
+      expected_request_schema = nil
+      parameter name: :id, in: :path, schema: { type: :integer }
+
+      produces 'application/json'
+      response '200', 'success response' do
+        expected_response_schema = nil
+        schema expected_response_schema
+
+        let(:id) { badge.id }
+
+        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
+end
diff --git a/spec/requests/api/schemas/json/badge_create_request.json b/spec/requests/api/schemas/json/badge_create_request.json
new file mode 100644
index 0000000..1f2314d
--- /dev/null
+++ b/spec/requests/api/schemas/json/badge_create_request.json
@@ -0,0 +1,17 @@
+{
+  "additionalProperties": false,
+  "properties": {
+    "name": {
+      "type": "string",
+      "description": "The name for the new badge."
+    },
+    "badge_type_id": {
+      "type": "integer",
+      "description": "The ID for the badge type. 1 for Gold, 2 for Silver, 3 for Bronze."
+    }
+  },
+  "required": [
+    "name",
+    "badge_type_id"
+  ]
+}
diff --git a/spec/requests/api/schemas/json/badge_create_response.json b/spec/requests/api/schemas/json/badge_create_response.json
new file mode 100644
index 0000000..74d57a1
--- /dev/null
+++ b/spec/requests/api/schemas/json/badge_create_response.json
@@ -0,0 +1,135 @@
+{
+  "additionalProperties": false,
+  "properties": {
+    "badge_types": {
+      "type": "array",
+      "items": [
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "id": {
+              "type": "integer"
+            },
+            "name": {
+              "type": "string"
+            },
+            "sort_order": {
+              "type": "integer"
+            }
+          },
+          "required": [
+            "id",
+            "name",
+            "sort_order"
+          ]
+        }
+      ]
+    },
+    "badge": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "id": {
+          "type": "integer"
+        },
+        "name": {
+          "type": "string"
+        },
+        "description": {
+          "type": "string"
+        },
+        "grant_count": {
+          "type": "integer"
+        },
+        "allow_title": {
+          "type": "boolean"
+        },
+        "multiple_grant": {
+          "type": "boolean"
+        },
+        "icon": {
+          "type": "string"
+        },
+        "image_url": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "listable": {
+          "type": "boolean"
+        },
+        "enabled": {
+          "type": "boolean"
+        },
+        "badge_grouping_id": {
+          "type": "integer"
+        },
+        "system": {
+          "type": "boolean"
+        },
+        "long_description": {
+          "type": "string"
+        },
+        "slug": {
+          "type": "string"
+        },
+        "manually_grantable": {
+          "type": "boolean"
+        },
+        "query": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "trigger": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "target_posts": {
+          "type": "boolean"
+        },
+        "auto_revoke": {
+          "type": "boolean"
+        },
+        "show_posts": {
+          "type": "boolean"
+        },
+        "badge_type_id": {
+          "type": "integer"
+        }
+      },
+      "required": [
+        "id",
+        "name",
+        "description",
+        "grant_count",
+        "allow_title",
+        "multiple_grant",
+        "icon",
+        "image_url",
+        "listable",
+        "enabled",
+        "badge_grouping_id",
+        "system",
+        "long_description",
+        "slug",
+        "manually_grantable",
+        "query",
+        "trigger",
+        "target_posts",
+        "auto_revoke",
+        "show_posts",
+        "badge_type_id"
+      ]
+    }
+  },
+  "required": [
+    "badge_types",
+    "badge"
+  ]
+}
diff --git a/spec/requests/api/schemas/json/badge_list_response.json b/spec/requests/api/schemas/json/badge_list_response.json
new file mode 100644
index 0000000..6179c10
--- /dev/null
+++ b/spec/requests/api/schemas/json/badge_list_response.json
@@ -0,0 +1,251 @@
+{
+  "additionalProperties": false,
+  "properties": {
+    "badges": {
+      "type": "array",
+      "items": [
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "id": {
+              "type": "integer"
+            },
+            "name": {
+              "type": "string"
+            },
+            "description": {
+              "type": "string"
+            },
+            "grant_count": {
+              "type": "integer"
+            },
+            "allow_title": {
+              "type": "boolean"
+            },
+            "multiple_grant": {
+              "type": "boolean"
+            },
+            "icon": {

[... diff too long, it was truncated ...]

GitHub sha: 5c6e7e3401f23b7e1673e8039dceb2e5b9c3f008

This commit appears in #13919 which was approved by CvX. It was merged by blake.