/organizations api docs (#19055)

* /organizations api docs

* Remove Listings support

spec/requests/api/v1/docs/organizations_spec.rb

@@ -0,0 +1,102 @@
+require "rails_helper"
+require "swagger_helper"
+
+# rubocop:disable RSpec/EmptyExampleGroup
+
+RSpec.describe "Api::V1::Docs::Articles" do
+  let(:organization) { create(:organization) }
+
+  describe "GET /organizations/{username}" do
+    before do
+      create_list(:user, 2).map do |user|
+        create(:organization_membership, user: user, organization: organization)
+      end
+      create(:article, organization: organization)
+    end
+
+    path "/api/organizations/{username}" do
+      get "An organization" do
+        tags "organizations"
+        security []
+        description "This endpoint allows the client to retrieve a single organization by their username"
+        operationId "getOrganization"
+        produces "application/json"
+        parameter name: :username, in: :path, type: :string, required: true
+
+        response "200", "An Organization" do
+          let(:username) { organization.username }
+          schema  type: :object,
+                  items: { "$ref": "#/components/schemas/Organization" }
+          add_examples
+          run_test!
+        end
+
+        response "404", "Not Found" do
+          let(:username) { "non-existent-username" }
+          add_examples
+          run_test!
+        end
+      end
+    end
+
+    path "/api/organizations/{username}/users" do
+      get "Organization's users" do
+        tags "organizations", "users"
+        security []
+        description "This endpoint allows the client to retrieve a list of users belonging to the organization
+
+It supports pagination, each page will contain `30` users by default."
+        operationId "getOrgUsers"
+        produces "application/json"
+        parameter name: :username, in: :path, type: :string, required: true
+        parameter "$ref": "#/components/parameters/pageParam"
+        parameter "$ref": "#/components/parameters/perPageParam30to1000"
+
+        response "200", "An Organization's users" do
+          let(:username) { organization.username }
+          schema  type: :array,
+                  items: { "$ref": "#/components/schemas/User" }
+          add_examples
+          run_test!
+        end
+
+        response "404", "Not Found" do
+          let(:username) { "non-existent-username" }
+          add_examples
+          run_test!
+        end
+      end
+    end
+
+    path "/api/organizations/{username}/articles" do
+      get "Organization's Articles" do
+        tags "organizations", "articles"
+        security []
+        description "This endpoint allows the client to retrieve a list of Articles belonging to the organization
+
+It supports pagination, each page will contain `30` users by default."
+        operationId "getOrgArticles"
+        produces "application/json"
+        parameter name: :username, in: :path, type: :string, required: true
+        parameter "$ref": "#/components/parameters/pageParam"
+        parameter "$ref": "#/components/parameters/perPageParam30to1000"
+
+        response "200", "An Organization's Articles" do
+          let(:username) { organization.username }
+          schema  type: :array,
+                  items: { "$ref": "#/components/schemas/ArticleIndex" }
+          add_examples
+          run_test!
+        end
+
+        response "404", "Not Found" do
+          let(:username) { "non-existent-username" }
+          add_examples
+          run_test!
+        end
+      end
+    end
+  end
+end
+
+# rubocop:enable RSpec/EmptyExampleGroup

spec/swagger_helper.rb

@@ -163,8 +163,8 @@ The default maximum value can be overridden by \"API_PER_PAGE_MAX\" environment
             type: :object,
             properties: {
               name: { type: :string },
-              bg_color_hex: { description: "Background color (hexadecimal)", type: :string },
-              text_color_hex: { description: "Text color (hexadecimal)", type: :string }
+              bg_color_hex: { description: "Background color (hexadecimal)", type: :string, nullable: true },
+              text_color_hex: { description: "Text color (hexadecimal)", type: :string, nullable: true }
             }
           },
           ArticleIndex: {
@@ -247,6 +247,24 @@ The default maximum value can be overridden by \"API_PER_PAGE_MAX\" environment
               }
             }
           },
+          Organization: {
+            description: "Representation of an Organization",
+            type: :object,
+            properties: {
+              type_of: { type: :string },
+              username: { type: :string },
+              name: { type: :string },
+              summary: { type: :string },
+              twitter_username: { type: :string },
+              github_username: { type: :string },
+              url: { type: :string },
+              location: { type: :string },
+              joined_at: { type: :string },
+              tech_stack: { type: :string },
+              tag_line: { type: :string, nullable: true },
+              story: { type: :string, nullable: true }
+            }
+          },
           FollowedTag: {
             description: "Representation of a followed tag",
             type: :object,
@@ -336,6 +354,23 @@ The default maximum value can be overridden by \"API_PER_PAGE_MAX\" environment
               profile_image_90: { description: "Profile image (90x90)", type: :string, format: :url }
             }
           },
+          User: {
+            description: "The representation of a user",
+            type: :object,
+            properties: {
+              type_of: { type: :string },
+              id: { type: :integer, format: :int64 },
+              username: { type: :string },
+              name: { type: :string },
+              summary: { type: :string, nullable: true },
+              twitter_username: { type: :string },
+              github_username: { type: :string },
+              website_url: { type: :string, nullable: true },
+              location: { type: :string, nullable: true },
+              joined_at: { type: :string },
+              profile_image: { type: :string }
+            }
+          },
           SharedPodcast: {
             description: "The podcast that the resource belongs to",
             type: :object,
@@ -355,23 +390,6 @@ The default maximum value can be overridden by \"API_PER_PAGE_MAX\" environment
               image_url: { description: "Podcast image url", type: :string, format: :url }
             }
           },
-          User: {
-            description: "The representation of a user",
-            type: :object,
-            properties: {
-              type_of: { type: :string },
-              id: { type: :string },
-              username: { type: :string },
-              name: { type: :string },
-              summary: { type: :string },
-              twitter_username: { type: :string },
-              github_username: { type: :string },
-              website_url: { type: :string },
-              location: { type: :string },
-              joined_at: { type: :string },
-              profile_image: { type: :string }
-            }
-          },
           UserInviteParam: {
             description: "User invite parameters",
             type: :object,