DEV: api documentation updates (#9612)

DEV: api documentation updates (#9612)

  • DEV: api documentation updates
  • Created a script to convert json responses to rswag
  • Documented several api endpoints
  • Switched rswag to use header based auth
  • Update script, fix some schema missmatches
diff --git a/script/json_to_rswag.rb b/script/json_to_rswag.rb
new file mode 100644
index 0000000..e3e25ea
--- /dev/null
+++ b/script/json_to_rswag.rb
@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+require 'json'
+
+# This script is used for development to help document rswag api responses.  It
+# takes a json response string as an input and converts it to ruby in the format
+# that rswag wants so that you can copy+paste it into the appropriate spec rather
+# than typing it by hand.
+#
+# example:
+#
+# ruby script/json_to_rswag.rb '{"success":true,"active":true,"message":"Your account is activated and ready to use.","user_id":18}'
+#
+# will output:
+#
+# schema type: :object, properties: {
+#   success: { type: :boolean },
+#   active: { type: :boolean },
+#   message: { type: :string },
+#   user_id: { type: :integer },
+# }
+
+class JsonToRswag
+
+  def initialize
+    @output = Array.new
+    @output.push("schema type: :object, properties: {")
+  end
+
+  def get_type(k, v)
+    type = ""
+    type = "integer" if v.is_a? Integer
+    type = "number" if v.is_a? Float
+    type = "object" if v.is_a? Hash
+    type = "array" if v.is_a? Array
+    type = "boolean" if v == true || v == false
+    type = "null" if v == nil
+    type = "string" if v.is_a? String
+    if type == ""
+      puts "Cannot determine type for:"
+      puts v
+      exit 1
+    end
+    type
+  end
+
+  def run(h, indent)
+    h.each do |k, v|
+      type = get_type(k, v)
+
+      if type == "object"
+        @output << "#{' ' * indent}#{k}: {"
+        @output << "#{' ' * (indent + 2)}type: :object,"
+        @output << "#{' ' * (indent + 2)}properties: {"
+        run(v, indent + 4)
+        @output << "#{' ' * indent}},"
+      end
+
+      if type == "array"
+        @output << "#{' ' * indent}#{k}: {"
+        @output << "#{' ' * (indent + 2)}type: :array,"
+        @output << "#{' ' * (indent + 2)}items: {"
+        a = v.first
+        if a.is_a? Hash
+          @output << "#{' ' * (indent + 4)}type: :object,"
+          @output << "#{' ' * (indent + 4)}properties: {"
+          run(a , indent + 6)
+          @output << "#{' ' * (indent + 2)}},"
+        else
+          @output << "#{' ' * (indent + 2)}},"
+        end
+        @output << "#{' ' * indent}},"
+      end
+
+      if type == "null"
+        @output << "#{' ' * indent}#{k}: { type: :string, nullable: true },"
+      elsif type != "object" && type != "array"
+        @output << "#{' ' * indent}#{k}: { type: :#{type} },"
+      end
+    end
+
+    @output << "#{' ' * (indent - 2)}}"
+  end
+
+  def print
+    puts @output
+  end
+
+end
+
+input = ARGV[0]
+
+if input == nil || input == ""
+  puts "Please pass in a json string."
+  exit 1
+end
+
+json = JSON.parse(input)
+
+json_to_rswag = JsonToRswag.new
+json_to_rswag.run(json, 2)
+json_to_rswag.print
diff --git a/spec/requests/api/categories_spec.rb b/spec/requests/api/categories_spec.rb
index 0c82cfa..5de0bde 100644
--- a/spec/requests/api/categories_spec.rb
+++ b/spec/requests/api/categories_spec.rb
@@ -4,6 +4,7 @@ require 'swagger_helper'
 describe 'categories' do
 
   let(:admin) { Fabricate(:admin) }
+  let!(:category) { Fabricate(:category, user: admin) }
 
   before do
     Jobs.run_immediately!
@@ -13,11 +14,7 @@ describe 'categories' do
   path '/categories.json' do
 
     post 'Creates a category' do
-      before do
-        Jobs.run_immediately!
-        sign_in(admin)
-      end
-      tags 'Category'
+      tags 'Categories'
       consumes 'application/json'
       parameter name: :category, in: :body, schema: {
         type: :object,
@@ -38,6 +35,46 @@ describe 'categories' do
                 id: { type: :integer },
                 name: { type: :string },
                 color: { type: :string },
+                text_color: { type: :string },
+                slug: { type: :string },
+                topic_count: { type: :integer },
+                post_count: { type: :integer },
+                position: { type: :integer },
+                description: { type: :string, nullable: true },
+                description_text: { type: :string, nullable: true },
+                topic_url: { type: :string },
+                read_restricted: { type: :boolean },
+                permission: { type: :integer, nullable: true },
+                notification_level: { type: :integer, nullable: true },
+                can_edit: { type: :boolean },
+                topic_template: { type: :string, nullable: true },
+                has_children: { type: :boolean, nullable: true },
+                sort_order: { type: :string, nullable: true },
+                show_subcategory_list: { type: :boolean },
+                num_featured_topics: { type: :integer },
+                default_view: { type: :string, nullable: true },
+                subcategory_list_style: { type: :string },
+                default_topic_period: { type: :string },
+                minimum_required_tags: { type: :integer },
+                navigate_to_first_post_after_read: { type: :boolean },
+                custom_fields: { type: :object },
+                min_tags_from_required_group: { type: :integer },
+                required_tag_group_name: { type: :string, nullable: true },
+                available_groups: { type: :array },
+                auto_close_hours: { type: :integer, nullable: true },
+                auto_close_based_on_last_post: { type: :boolean },
+                group_permissions: { type: :array },
+                email_in: { type: :boolean, nullable: true },
+                email_in_allow_strangers: { type: :boolean },
+                mailinglist_mirror: { type: :boolean },
+                all_topics_wiki: { type: :boolean },
+                can_delete: { type: :boolean },
+                cannot_delete_reason: { type: :string, nullable: true },
+                allow_badges: { type: :boolean },
+                topic_featured_link_allowed: { type: :boolean },
+                search_priority: { type: :integer },
+                uploaded_logo: { type: :string, nullable: true },
+                uploaded_background: { type: :string, nullable: true },
               },
               required: ["id"]
             }
@@ -49,7 +86,7 @@ describe 'categories' do
     end
 
     get 'Retreives a list of categories' do
-      tags 'Category'
+      tags 'Categories'
       produces 'application/json'
 
       response '200', 'categories response' do
@@ -62,7 +99,46 @@ describe 'categories' do
               draft: { type: :string, nullable: true },
               draft_key: { type: :string },
               draft_sequence: { type: :integer },
-              categories: { type: :array },
+              categories: {
+                type: :array,
+                items: {
+                  type: :object,
+                  properties: {
+                    id: { type: :integer },
+                    name: { type: :string },
+                    color: { type: :string },
+                    text_color: { type: :string },
+                    slug: { type: :string },
+                    topic_count: { type: :integer },
+                    post_count: { type: :integer },
+                    position: { type: :integer },
+                    description: { type: :string, nullable: true },
+                    description_text: { type: :string, nullable: true },
+                    topic_url: { type: :string, nullable: true },
+                    read_restricted: { type: :boolean },
+                    permission: { type: :integer, nullable: true },
+                    notification_level: { type: :integer, nullable: true },
+                    can_edit: { type: :boolean },
+                    topic_template: { type: :string, nullable: true },
+                    has_children: { type: :boolean, nullable: true },
+                    sort_order: { type: :string, nullable: true },

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

GitHub sha: ab919332

1 Like

This commit appears in #9612 which was merged by blake.