[API v1 docs] Followed Tags (#18952)

* Followed Tags swag docs

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

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

* Add to swagger helper

* minor tweaks

* more cleanup

* syntax change

* name change

* User doesn't have to be an admin

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

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

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

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

* update v1 json structure

* Update spec/swagger_helper.rb

Co-authored-by: Ridhwana <Ridhwana.Khan16@gmail.com>

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

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

* re-generate swagger file

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

Co-authored-by: Ridhwana <Ridhwana.Khan16@gmail.com>

* regenerated swagger file

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Co-authored-by: Ridhwana <Ridhwana.Khan16@gmail.com>

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

@@ -0,0 +1,52 @@
+require "rails_helper"
+require "swagger_helper"
+
+# rubocop:disable RSpec/EmptyExampleGroup
+# rubocop:disable RSpec/VariableName
+
+RSpec.describe "Api::V1::Docs::FollowedTags" do
+  let(:Accept) { "application/vnd.forem.api-v1+json" }
+  let(:api_secret) { create(:api_secret) }
+  let(:user) { api_secret.user }
+  let(:tag1) { create(:tag) }
+  let(:tag2) { create(:tag) }
+
+  let(:tag1_json) { { id: tag1.id, name: tag1.name, points: 1.0 } }
+  let(:tag2_json) { { id: tag2.id, name: tag2.name, points: 1.0 } }
+
+  before do
+    [tag1, tag2].each { |tag| user.follow(tag) }
+  end
+
+  describe "GET /follows/tags" do
+    path "/api/follows/tags" do
+      get "Followed Tags" do
+        tags "followed_tags"
+        description(<<-DESCRIBE.strip)
+        This endpoint allows the client to retrieve a list of the tags they follow.
+        DESCRIBE
+        operationId "getFollowedTags"
+        produces "application/json"
+
+        response "401", "unauthorized" do
+          let(:"api-key") { nil }
+          add_examples
+
+          run_test!
+        end
+
+        response "200", "A List of followed tags" do
+          let(:"api-key") { api_secret.secret }
+          schema  type: :array,
+                  items: { "$ref": "#/components/schemas/FollowedTag" }
+          add_examples
+
+          run_test!
+        end
+      end
+    end
+  end
+end
+
+# rubocop:enable RSpec/EmptyExampleGroup
+# rubocop:enable RSpec/VariableName

spec/swagger_helper.rb

@@ -204,6 +204,16 @@ The default maximum value can be overridden by \"API_PER_PAGE_MAX\" environment
                          crossposted_at published_at last_comment_at published_timestamp user
                          reading_time_minutes]
           },
+          FollowedTag: {
+            description: "Representation of a followed tag",
+            type: :object,
+            properties: {
+              id: { description: "Tag id", type: :integer, format: :int64 },
+              name: { type: :string },
+              points: { type: :number, format: :float }
+            },
+            required: %w[id name points]
+          },
           PodcastEpisodeIndex: {
             description: "Representation of a podcast episode returned in a list",
             type: :object,

swagger/v1/api_v1.json

@@ -1297,6 +1297,41 @@
           }
         }
       }
+    },
+    "/api/follows/tags": {
+      "get": {
+        "summary": "FollowedTags",
+        "tags": ["followed_tags"],
+        "description": "This endpoint allows the client to retrieve a list of the tags they follow.",
+        "operationId": "getFollowedTags",
+        "responses": {
+          "200": {
+            "description": "A list of followed tags",
+            "content": {
+              "application/json": {
+                "example": [
+                  {
+                    "id": 7875,
+                    "name": "Tag1",
+                    "points": 1
+                  },
+                  {
+                    "id": 7876,
+                    "name": "Tag2",
+                    "points": 1
+                  }
+                ],
+                "schema": {
+                  "type": "array",
+                  "items": {
+                    "$ref": "#/components/schemas/FollowedTag"
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
     }
   },
   "servers": [
@@ -1555,6 +1590,28 @@
           "reading_time_minutes"
         ]
       },
+      "FollowedTag": {
+        "description": "Representation of a tag",
+        "type": "object",
+        "properties": {
+          "name": {
+            "type": "string"
+          },
+          "id": {
+            "type": "integer",
+            "format": "int32"
+          },
+          "points": {
+            "type": "integer",
+            "format": "int32"
+          }
+        },
+        "required": [
+          "name",
+          "id",
+          "points"
+        ]
+      },
       "PodcastEpisodeIndex": {
         "description": "Representation of a podcast episode returned in a list",
         "type": "object",