/tags api docs (forem#19048)

* /tags api docs

* Merge main

Author: fdocr

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

@@ -21,7 +21,7 @@
   describe "GET /follows/tags" do
     path "/api/follows/tags" do
       get "Followed Tags" do
-        tags "followed_tags"
+        tags "followed_tags", "tags"
         description(<<-DESCRIBE.strip)
         This endpoint allows the client to retrieve a list of the tags they follow.
         DESCRIBE

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

@@ -0,0 +1,34 @@
+require "rails_helper"
+require "swagger_helper"
+
+# rubocop:disable RSpec/EmptyExampleGroup
+
+describe "GET /tags" do
+  before { create_list(:tag, 3) }
+
+  path "/api/tags" do
+    get "Tags" do
+      tags "tags"
+      security []
+      description "This endpoint allows the client to retrieve a list of tags that can be used to tag articles.
+
+It will return tags ordered by popularity.
+
+It supports pagination, each page will contain 10 tags by default."
+      operationId "getTags"
+      produces "application/json"
+      parameter "$ref": "#/components/parameters/pageParam"
+      parameter "$ref": "#/components/parameters/perPageParam10to1000"
+
+      response "200", "A List of all tags" do
+        schema  type: :array,
+                items: { "$ref": "#/components/schemas/Tag" }
+        add_examples
+
+        run_test!
+      end
+    end
+  end
+end
+
+# rubocop:enable RSpec/EmptyExampleGroup

spec/swagger_helper.rb

@@ -257,6 +257,16 @@
             },
             required: %w[id name points]
           },
+          Tag: {
+            description: "Representation of a tag",
+            type: :object,
+            properties: {
+              id: { description: "Tag id", type: :integer, format: :int64 },
+              name: { type: :string },
+              bg_color_hex: { type: :string, nullable: true },
+              text_color_hex: { type: :string, nullable: true }
+            }
+          },
           Page: {
             description: "Representation of a page object",
             type: :object,