API V1 Users docs (#19046)

* /users/me api docs

* Updated api_v1.json

* Missing users api docs

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

@@ -307,7 +307,7 @@ It supports pagination, each page will contain 30 articles by default."
   describe "GET /articles/me" do
     path "/api/articles/me" do
       get "User's articles" do
-        tags "articles"
+        tags "articles", "users"
         description "This endpoint allows the client to retrieve a list of published articles on behalf of an authenticated user.
 
 \"Articles\" are all the posts that users create on DEV that typically show up in the feed. They can be a blog post, a discussion question, a help thread etc. but is referred to as article within the code.
@@ -340,7 +340,7 @@ It will return published articles with pagination. By default a page will contai
 
     path "/api/articles/me/published" do
       get "User's published articles" do
-        tags "articles"
+        tags "articles", "users"
         description "This endpoint allows the client to retrieve a list of published articles on behalf of an authenticated user.
 
 \"Articles\" are all the posts that users create on DEV that typically show up in the feed. They can be a blog post, a discussion question, a help thread etc. but is referred to as article within the code.
@@ -373,7 +373,7 @@ It will return published articles with pagination. By default a page will contai
 
     path "/api/articles/me/unpublished" do
       get "User's unpublished articles" do
-        tags "articles"
+        tags "articles", "users"
         description "This endpoint allows the client to retrieve a list of unpublished articles on behalf of an authenticated user.
 
 \"Articles\" are all the posts that users create on DEV that typically show up in the feed. They can be a blog post, a discussion question, a help thread etc. but is referred to as article within the code.
@@ -406,7 +406,7 @@ It will return unpublished articles with pagination. By default a page will cont
 
     path "/api/articles/me/all" do
       get "User's all articles" do
-        tags "articles"
+        tags "articles", "users"
         description "This endpoint allows the client to retrieve a list of all articles on behalf of an authenticated user.
 
 \"Articles\" are all the posts that users create on DEV that typically show up in the feed. They can be a blog post, a discussion question, a help thread etc. but is referred to as article within the code.

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

@@ -17,6 +17,31 @@ RSpec.describe "Api::V1::Docs::Users" do
     user.add_role(:admin)
   end
 
+  describe "GET /users/me" do
+    path "/api/users/me" do
+      get "The authenticated user" do
+        tags "users"
+        description "This endpoint allows the client to retrieve information about the authenticated user"
+        operationId "getUserMe"
+        produces "application/json"
+
+        response 200, "successful" do
+          let(:"api-key") { api_secret.secret }
+          schema type: :object,
+                 items: { "$ref": "#/components/schemas/User" }
+          add_examples
+          run_test!
+        end
+
+        response "401", "Unauthorized" do
+          let(:"api-key") { "bad_api_secret" }
+          add_examples
+          run_test!
+        end
+      end
+    end
+  end
+
   describe "GET /users/:id" do
     path "/api/users/{id}" do
       get "A User" do
@@ -32,6 +57,8 @@ For complete documentation, see the v0 API docs: https://developers.forem.com/ap
         response(200, "successful") do
           let(:"api-key") { api_secret.secret }
           let(:id) { user.id }
+          schema type: :object,
+                 items: { "$ref": "#/components/schemas/User" }
 
           run_test!
         end
@@ -155,6 +182,51 @@ in the UI, so if you want them to know about this, you must notify them."
       end
     end
   end
+
+  describe "POST /api/admin/users" do
+    before do
+      user.add_role(:super_admin)
+    end
+
+    path "/api/admin/users" do
+      post "Invite a User" do
+        tags "users"
+        description "This endpoint allows the client to trigger an invitation to the provided email address.
+
+        It requires a token from a user with `super_admin` privileges."
+        operationId "postAdminUsersCreate"
+        produces "application/json"
+        consumes "application/json"
+        parameter name: :invitation,
+                  in: :body,
+                  description: "User invite params",
+                  schema: { "$ref": "#/components/schemas/UserInviteParam" }
+
+        response "200", "Successful" do
+          let(:"api-key") { api_secret.secret }
+          let(:invitation) { { name: "User McUser", email: "user@mcuser.com" } }
+          add_examples
+          run_test!
+        end
+
+        response "401", "Unauthorized" do
+          let(:regular_user) { create(:user) }
+          let(:low_security_api_secret) { create(:api_secret, user: regular_user) }
+          let(:"api-key") { low_security_api_secret.secret }
+          let(:invitation) { { name: "User McUser", email: "user@mcuser.com" } }
+          add_examples
+          run_test!
+        end
+
+        response "422", "Unprocessable Entity" do
+          let(:"api-key") { api_secret.secret }
+          let(:invitation) { {} }
+          add_examples
+          run_test!
+        end
+      end
+    end
+  end
 end
 # rubocop:enable RSpec/VariableName
 # rubocop:enable RSpec/EmptyExampleGroup

spec/swagger_helper.rb

@@ -323,6 +323,31 @@ The default maximum value can be overridden by \"API_PER_PAGE_MAX\" environment
               created_at: { type: :string, format: "date-time" },
               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,
+            properties: {
+              email: { type: :string },
+              name: { type: :string, nullable: true }
+            }
           }
         }
       }