DEV: More API Doc improvements (#11849)

- Create helper wrapper method `load_spec_schema(name)`
- A minor change to tag_group_create response schema
- Document the uploads endpoint

spec/requests/api/schemas/json/tag_group_create_response.json

@@ -27,12 +27,7 @@
           "type": "boolean"
         },
         "permissions": {
-          "type": "object",
-          "properties": {
-            "everyone": {
-              "type": "integer"
-            }
-          }
+          "type": "object"
         }
       },
       "required": [

spec/requests/api/schemas/json/upload_create_request.json

@@ -0,0 +1,30 @@
+{
+  "additionalProperties": false,
+  "properties": {
+    "type": {
+      "type": "string",
+      "enum": [
+        "avatar",
+        "profile_background",
+        "card_background",
+        "custom_emoji",
+        "composer"
+      ]
+    },
+    "user_id": {
+      "type": "integer",
+      "description": "required if uploading an avatar"
+    },
+    "synchronous": {
+      "type": "boolean",
+      "description": "Use this flag to return an id and url"
+    },
+    "file": {
+      "type": "string",
+      "format": "binary"
+    }
+  },
+  "required": [
+    "type"
+  ]
+}

spec/requests/api/schemas/json/upload_create_response.json

@@ -0,0 +1,59 @@
+{
+  "additionalProperties": false,
+  "properties": {
+    "id": {
+      "type": "integer"
+    },
+    "url": {
+      "type": "string"
+    },
+    "original_filename": {
+      "type": "string"
+    },
+    "filesize": {
+      "type": "integer"
+    },
+    "width": {
+      "type": "integer"
+    },
+    "height": {
+      "type": "integer"
+    },
+    "thumbnail_width": {
+      "type": "integer"
+    },
+    "thumbnail_height": {
+      "type": "integer"
+    },
+    "extension": {
+      "type": "string"
+    },
+    "short_url": {
+      "type": "string"
+    },
+    "short_path": {
+      "type": "string"
+    },
+    "retain_hours": {
+      "type": ["string", "null"]
+    },
+    "human_filesize": {
+      "type": "string"
+    }
+  },
+  "required": [
+    "id",
+    "url",
+    "original_filename",
+    "filesize",
+    "width",
+    "height",
+    "thumbnail_width",
+    "thumbnail_height",
+    "extension",
+    "short_url",
+    "short_path",
+    "retain_hours",
+    "human_filesize"
+  ]
+}

spec/requests/api/tags_spec.rb

@@ -60,13 +60,13 @@ describe 'tags' do
     post 'Creates a tag group' do
       tags 'Tags'
       consumes 'application/json'
-      expected_request_schema = SpecSchemas::SpecLoader.new('tag_group_create_request').load
+      expected_request_schema = load_spec_schema('tag_group_create_request')
 
       parameter name: :params, in: :body, schema: expected_request_schema
 
       produces 'application/json'
       response '200', 'tag group created' do
-        expected_response_schema = SpecSchemas::SpecLoader.new('tag_group_create_response').load
+        expected_response_schema = load_spec_schema('tag_group_create_response')
 
         let(:params) { { 'name' => 'todo' } }
 

spec/requests/api/uploads_spec.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+require 'swagger_helper'
+
+describe 'uploads' do
+
+  let(:admin) { Fabricate(:admin) }
+  let(:logo_file) { file_from_fixtures("logo.png") }
+  let(:logo) { Rack::Test::UploadedFile.new(logo_file) }
+
+  before do
+    Jobs.run_immediately!
+    sign_in(admin)
+  end
+
+  path '/uploads.json' do
+    post 'Creates an upload' do
+      tags 'Uploads'
+      consumes 'multipart/form-data'
+
+      expected_request_schema = load_spec_schema('upload_create_request')
+      parameter name: :params, in: :body, schema: expected_request_schema
+
+      let(:params) { {
+        type: 'avatar',
+        user_id: admin.id,
+        synchronous: true,
+        file: logo
+      } }
+
+      produces 'application/json'
+      response '200', 'file uploaded' do
+        expected_response_schema = load_spec_schema('upload_create_response')
+        schema(expected_response_schema)
+
+        # Skipping this test for now until https://github.com/rswag/rswag/issues/348
+        # is resolved. This still allows the docs to be generated for this endpoint though.
+        xit
+      end
+
+    end
+  end
+end

spec/swagger_helper.rb

@@ -9,6 +9,10 @@ Dir["./spec/requests/api/schemas/*.rb"].each { |file| require file }
 # Require shared spec examples
 Dir["./spec/requests/api/shared/*.rb"].each { |file| require file }
 
+def load_spec_schema(name)
+  SpecSchemas::SpecLoader.new(name).load
+end
+
 RSpec.configure do |config|
   # Specify a root folder where Swagger JSON files are generated
   # NOTE: If you're using the rswag-api to serve API descriptions, you'll need