DEV: Add missing operationIds to the api docs (#14235)

From the openapi spec:

 https://spec.openapis.org/oas/latest.html#fixed-fields-7

each endpoint needs to have an `operationId`:

> Unique string used to identify the operation. The id MUST be unique
> among all operations described in the API. The operationId value is
> case-sensitive. Tools and libraries MAY use the operationId to uniquely
> identify an operation, therefore, it is RECOMMENDED to follow common
> programming naming conventions.

Running the linter on our openapi.json file with this command:

`npx @redocly/openapi-cli lint openapi.json`

produced the following warning on all of our endpoints:

> Operation object should contain `operationId` field

This commit resolves these warnings by adding an operationId field to
each endpoint.

spec/requests/api/backups_spec.rb

@@ -36,6 +36,7 @@ describe 'backups' do
   path '/admin/backups.json' do
     get 'List backups' do
       tags 'Backups'
+      operationId 'getBackups'
       consumes 'application/json'
       expected_request_schema = nil
 
@@ -53,6 +54,7 @@ describe 'backups' do
 
     post 'Create backup' do
       tags 'Backups'
+      operationId 'createBackup'
       consumes 'application/json'
       expected_request_schema = load_spec_schema('backups_create_request')
       parameter name: :params, in: :body, schema: expected_request_schema
@@ -81,6 +83,7 @@ describe 'backups' do
   path '/admin/backups/{filename}' do
     put 'Send download backup email' do
       tags 'Backups'
+      operationId 'sendDownloadBackupEmail'
       consumes 'application/json'
       expected_request_schema = nil
       parameter name: :filename, in: :path, type: :string, required: true
@@ -100,6 +103,7 @@ describe 'backups' do
 
     get 'Download backup' do
       tags 'Backups'
+      operationId 'downloadBackup'
       consumes 'application/json'
       expected_request_schema = nil
       parameter name: :filename, in: :path, type: :string, required: true

spec/requests/api/badges_spec.rb

@@ -15,6 +15,7 @@ describe 'badges' do
 
     get 'List badges' do
       tags 'Badges'
+      operationId 'adminListBadges'
       consumes 'application/json'
       expected_request_schema = nil
 
@@ -32,6 +33,7 @@ describe 'badges' do
 
     post 'Create badge' do
       tags 'Badges'
+      operationId 'createBadge'
       consumes 'application/json'
       expected_request_schema = load_spec_schema('badge_create_request')
       parameter name: :params, in: :body, schema: expected_request_schema
@@ -58,6 +60,7 @@ describe 'badges' do
 
     put 'Update badge' do
       tags 'Badges'
+      operationId 'updateBadge'
       consumes 'application/json'
       expected_request_schema = load_spec_schema('badge_update_request')
       parameter name: :id, in: :path, schema: { type: :integer }
@@ -84,6 +87,7 @@ describe 'badges' do
 
     delete 'Delete badge' do
       tags 'Badges'
+      operationId 'deleteBadge'
       consumes 'application/json'
       expected_request_schema = nil
       parameter name: :id, in: :path, schema: { type: :integer }

spec/requests/api/categories_spec.rb

@@ -15,6 +15,7 @@ describe 'categories' do
 
     post 'Creates a category' do
       tags 'Categories'
+      operationId 'createCategory'
       consumes 'application/json'
       expected_request_schema = load_spec_schema('category_create_request')
       parameter name: :params, in: :body, schema: expected_request_schema
@@ -35,6 +36,7 @@ describe 'categories' do
 
     get 'Retrieves a list of categories' do
       tags 'Categories'
+      operationId 'listCategories'
       consumes 'application/json'
       expected_request_schema = nil
 
@@ -55,6 +57,7 @@ describe 'categories' do
 
     put 'Updates a category' do
       tags 'Categories'
+      operationId 'updateCategory'
       consumes 'application/json'
       expected_request_schema = load_spec_schema('category_create_request')
       parameter name: :id, in: :path, schema: { type: :integer }
@@ -80,6 +83,7 @@ describe 'categories' do
 
     get 'List topics' do
       tags 'Categories'
+      operationId 'listCategoryTopics'
       produces 'application/json'
       parameter name: :slug, in: :path, schema: { type: :string }
       parameter name: :id, in: :path, schema: { type: :integer }
@@ -105,6 +109,7 @@ describe 'categories' do
 
     get 'Show category' do
       tags 'Categories'
+      operationId 'getCategory'
       consumes 'application/json'
       parameter name: :id, in: :path, schema: { type: :integer }
       expected_request_schema = nil

spec/requests/api/groups_spec.rb

@@ -13,6 +13,7 @@ describe 'groups' do
   path '/admin/groups.json' do
     post 'Creates a group' do
       tags 'Groups'
+      operationId 'createGroup'
       consumes 'application/json'
       parameter name: :group, in: :body, schema: {
         type: :object,
@@ -78,6 +79,7 @@ describe 'groups' do
   path '/admin/groups/{id}.json' do
     delete 'Delete a group' do
       tags 'Groups'
+      operationId 'deleteGroup'
       consumes 'application/json'
       parameter name: :id, in: :path, type: :integer
       expected_request_schema = nil
@@ -99,6 +101,7 @@ describe 'groups' do
   path '/groups/{id}.json' do
     put 'Update a group' do
       tags 'Groups'
+      operationId 'updateGroup'
       consumes 'application/json'
       parameter name: :id, in: :path, type: :integer
       parameter name: :group, in: :body, schema: {
@@ -128,6 +131,7 @@ describe 'groups' do
 
     get 'Get a group' do
       tags 'Groups'
+      operationId 'getGroup'
       consumes 'application/json'
       parameter name: :id, in: :path, type: :string, example: 'name', description: "Use group name instead of id"
       expected_request_schema = nil
@@ -150,6 +154,7 @@ describe 'groups' do
   path '/groups/{id}/members.json' do
     get 'List group members' do
       tags 'Groups'
+      operationId 'listGroupMembers'
       consumes 'application/json'
       parameter name: :id, in: :path, type: :string, example: 'name', description: "Use group name instead of id"
       expected_request_schema = nil
@@ -170,6 +175,7 @@ describe 'groups' do
 
     put 'Add group members' do
       tags 'Groups'
+      operationId 'addGroupMembers'
       consumes 'application/json'
       parameter name: :id, in: :path, type: :integer
       expected_request_schema = load_spec_schema('group_add_members_request')
@@ -195,6 +201,7 @@ describe 'groups' do
 
     delete 'Remove group members' do
       tags 'Groups'
+      operationId 'removeGroupMembers'
       consumes 'application/json'
       parameter name: :id, in: :path, type: :integer
       expected_request_schema = load_spec_schema('group_remove_members_request')
@@ -222,6 +229,7 @@ describe 'groups' do
   path '/groups.json' do
     get 'List groups' do
       tags 'Groups'
+      operationId 'listGroups'
       consumes 'application/json'
       expected_request_schema = nil
 

spec/requests/api/invites_spec.rb

@@ -9,6 +9,7 @@ describe 'invites' do
   path '/invites.json' do
     post 'Create an invite' do
       tags 'Invites'
+      operationId 'createInvite'
       consumes 'application/json'
       parameter name: 'Api-Key', in: :header, type: :string, required: true
       parameter name: 'Api-Username', in: :header, type: :string, required: true

spec/requests/api/notifications_spec.rb

@@ -15,6 +15,7 @@ describe 'notifications' do
 
     get 'Get the notifications that belong to the current user' do
       tags 'Notifications'
+      operationId 'getNotifications'
 
       produces 'application/json'
       response '200', 'notifications' do
@@ -60,6 +61,7 @@ describe 'notifications' do
 
     put 'Mark notifications as read' do
       tags 'Notifications'
+      operationId 'markNotificationsAsRead'
       consumes 'application/json'
       parameter name: :notification, in: :body, schema: {
         type: :object,

spec/requests/api/posts_spec.rb

@@ -16,6 +16,7 @@ describe 'posts' do
 
     get 'List latest posts across topics' do
       tags 'Posts'
+      operationId 'listPosts'
       parameter name: 'Api-Key', in: :header, type: :string, required: true
       parameter name: 'Api-Username', in: :header, type: :string, required: true
       produces 'application/json'
@@ -98,6 +99,7 @@ describe 'posts' do
 
     post 'Creates a new topic, a new post, or a private message' do
       tags 'Posts', 'Topics', 'Private Messages'
+      operationId 'createTopicPostPM'
       consumes 'application/json'
       expected_request_schema = load_spec_schema('topic_create_request')
       parameter name: :params, in: :body, schema: expected_request_schema
@@ -121,6 +123,7 @@ describe 'posts' do
 
     get 'Retrieve a single post' do
       tags 'Posts'
+      operationId 'getPost'
       parameter name: 'Api-Key', in: :header, type: :string, required: true
       parameter name: 'Api-Username', in: :header, type: :string, required: true
       parameter name: :id, in: :path, schema: { type: :string }
@@ -194,6 +197,7 @@ describe 'posts' do
 
     put 'Update a single post' do
       tags 'Posts'
+      operationId 'updatePost'
       consumes 'application/json'
       parameter name: 'Api-Key', in: :header, type: :string, required: true
       parameter name: 'Api-Username', in: :header, type: :string, required: true
@@ -292,6 +296,7 @@ describe 'posts' do
   path '/posts/{id}/locked.json' do
     put 'Lock a post from being edited' do
       tags 'Posts'
+      operationId 'lockPost'
       consumes 'application/json'
       parameter name: 'Api-Key', in: :header, type: :string, required: true
       parameter name: 'Api-Username', in: :header, type: :string, required: true
@@ -324,6 +329,7 @@ describe 'posts' do
   path '/post_actions.json' do
     post 'Like a post and other actions' do
       tags 'Posts'
+      operationId 'performPostAction'
       consumes 'application/json'
       parameter name: 'Api-Key', in: :header, type: :string, required: true
       parameter name: 'Api-Username', in: :header, type: :string, required: true

spec/requests/api/private_messages_spec.rb

@@ -14,6 +14,7 @@ describe 'private messages' do
 
     get 'Get a list of private messages for a user' do
       tags 'Private Messages'
+      operationId 'listUserPrivateMessages'
       parameter name: :username, in: :path, schema: { type: :string }
 
       produces 'application/json'
@@ -123,6 +124,7 @@ describe 'private messages' do
 
     get 'Get a list of private messages sent for a user' do
       tags 'Private Messages'
+      operationId 'getUserSentPrivateMessages'
       parameter name: :username, in: :path, schema: { type: :string }
 
       produces 'application/json'

spec/requests/api/search_spec.rb

@@ -13,6 +13,7 @@ describe 'groups' do
   path '/search.json' do
     get 'Search for a term' do
       tags 'Search'
+      operationId 'search'
       consumes 'application/json'
       parameter(
         name: :q,

spec/requests/api/tags_spec.rb

@@ -17,6 +17,7 @@ describe 'tags' do
 
     get 'Get a list of tag groups' do
       tags 'Tags'
+      operationId 'listTagGroups'
 
       produces 'application/json'
       response '200', 'tags' do
@@ -59,6 +60,7 @@ describe 'tags' do
 
     post 'Creates a tag group' do
       tags 'Tags'
+      operationId 'createTagGroup'
       consumes 'application/json'
       expected_request_schema = load_spec_schema('tag_group_create_request')
 
@@ -85,6 +87,7 @@ describe 'tags' do
 
     get 'Get a single tag group' do
       tags 'Tags'
+      operationId 'getTagGroup'
       consumes 'application/json'
       parameter name: :id, in: :path, schema: { type: :string }
 
@@ -127,6 +130,7 @@ describe 'tags' do
 
     put 'Update tag group' do
       tags 'Tags'
+      operationId 'updateTagGroup'
       consumes 'application/json'
       parameter name: :id, in: :path, schema: { type: :string }
       parameter name: :put_body, in: :body, schema: {
@@ -177,6 +181,7 @@ describe 'tags' do
 
     get 'Get a list of tags' do
       tags 'Tags'
+      operationId 'listTags'
 
       produces 'application/json'
       response '200', 'notifications' do
@@ -215,6 +220,7 @@ describe 'tags' do
 
     get 'Get a specific tag' do
       tags 'Tags'
+      operationId 'getTag'
       parameter name: :name, in: :path, schema: { type: :string }
 
       produces 'application/json'

spec/requests/api/topics_spec.rb

@@ -9,6 +9,7 @@ describe 'topics' do
   path '/t/{id}/posts.json' do
     get 'Get specific posts from a topic' do
       tags 'Topics'
+      operationId 'getSpecificPostsFromTopic'
       consumes 'application/json'
       parameter name: 'Api-Key', in: :header, type: :string, required: true
       parameter name: 'Api-Username', in: :header, type: :string, required: true
@@ -107,6 +108,7 @@ describe 'topics' do
   path '/t/{id}.json' do
     get 'Get a single topic' do
       tags 'Topics'
+      operationId 'getTopic'
       consumes 'application/json'
       parameter name: 'Api-Key', in: :header, type: :string, required: true
       parameter name: 'Api-Username', in: :header, type: :string, required: true
@@ -375,6 +377,7 @@ describe 'topics' do
 
     delete 'Remove a topic' do
       tags 'Topics'
+      operationId 'removeTopic'
       consumes 'application/json'
       parameter name: 'Api-Key', in: :header, type: :string, required: true
       parameter name: 'Api-Username', in: :header, type: :string, required: true
@@ -392,6 +395,7 @@ describe 'topics' do
   path '/t/-/{id}.json' do
     put 'Update a topic' do
       tags 'Topics'
+      operationId 'updateTopic'
       consumes 'application/json'
       parameter name: 'Api-Key', in: :header, type: :string, required: true
       parameter name: 'Api-Username', in: :header, type: :string, required: true
@@ -440,6 +444,7 @@ describe 'topics' do
   path '/t/{id}/invite.json' do
     post 'Invite to topic' do
       tags 'Topics', 'Invites'
+      operationId 'inviteToTopic'
       consumes 'application/json'
       parameter name: 'Api-Key', in: :header, type: :string, required: true
       parameter name: 'Api-Username', in: :header, type: :string, required: true
@@ -482,6 +487,7 @@ describe 'topics' do
   path '/t/{id}/bookmark.json' do
     put 'Bookmark topic' do
       tags 'Topics'
+      operationId 'bookmarkTopic'
       consumes 'application/json'
       parameter name: 'Api-Key', in: :header, type: :string, required: true
       parameter name: 'Api-Username', in: :header, type: :string, required: true
@@ -501,6 +507,7 @@ describe 'topics' do
   path '/t/{id}/status.json' do
     put 'Update the status of a topic' do
       tags 'Topics'
+      operationId 'updateTopicStatus'
       consumes 'application/json'
       parameter name: 'Api-Key', in: :header, type: :string, required: true
       parameter name: 'Api-Username', in: :header, type: :string, required: true
@@ -543,6 +550,7 @@ describe 'topics' do
   path '/latest.json' do
     get 'Get the latest topics' do
       tags 'Topics'
+      operationId 'listLatestTopics'
       consumes 'application/json'
       parameter name: 'Api-Key', in: :header, type: :string, required: true
       parameter name: 'Api-Username', in: :header, type: :string, required: true
@@ -649,106 +657,10 @@ describe 'topics' do
     end
   end
 
-  path '/top.json' do
-    get 'Get the top topics' do
-      tags 'Topics'
-      consumes 'application/json'
-      parameter name: 'Api-Key', in: :header, type: :string, required: true
-      parameter name: 'Api-Username', in: :header, type: :string, required: true
-
-      produces 'application/json'
-      response '200', 'topic updated' do
-        schema type: :object, properties: {
-          users: {
-            type: :array,
-            items: {
-              type: :object,
-              properties: {
-                id: { type: :integer },
-                username: { type: :string },
-                name: { type: :string },
-                avatar_template: { type: :string },
-              }
-            },
-          },
-          primary_groups: {
-            type: :array,
-            items: {
-            },
-          },
-          topic_list: {
-            type: :object,
-            properties: {
-              can_create_topic: { type: :boolean },
-              draft: { type: [:string, :null] },
-              draft_key: { type: :string },
-              draft_sequence: { type: :integer },
-              for_period: { type: :string },
-              per_page: { type: :integer },
-              topics: {
-                type: :array,
-                items: {
-                  type: :object,
-                  properties: {
-                    id: { type: :integer },
-                    title: { type: :string },
-                    fancy_title: { type: :string },
-                    slug: { type: :string },
-                    posts_count: { type: :integer },
-                    reply_count: { type: :integer },
-                    highest_post_number: { type: :integer },
-                    image_url: { type: [:string, :null] },
-                    created_at: { type: :string },
-                    last_posted_at: { type: :string },
-                    bumped: { type: :boolean },
-                    bumped_at: { type: :string },
-                    archetype: { type: :string },
-                    unseen: { type: :boolean },
-                    last_read_post_number: { type: :integer },
-                    unread_posts: { type: :integer },
-                    pinned: { type: :boolean },
-                    unpinned: { type: :boolean },
-                    visible: { type: :boolean },
-                    closed: { type: :boolean },
-                    archived: { type: :boolean },
-                    notification_level: { type: :integer },
-                    bookmarked: { type: :boolean },
-                    liked: { type: :boolean },
-                    views: { type: :integer },
-                    like_count: { type: :integer },
-                    has_summary: { type: :boolean },
-                    last_poster_username: { type: :string },
-                    category_id: { type: :integer },
-                    op_like_count: { type: :integer },
-                    pinned_globally: { type: :boolean },
-                    featured_link: { type: [:string, :null] },
-                    posters: {
-                      type: :array,
-                      items: {
-                        type: :object,
-                        properties: {
-                          extras: { type: [:string, :null] },
-                          description: { type: :string },
-                          user_id: { type: :integer },
-                          primary_group_id: { type: [:string, :null] },
-                        }
-                      },
-                    },
-                  }
-                },
-              },
-            }
-          },
-        }
-
-        run_test!
-      end
-    end
-  end
-
   path '/top.json' do
     get 'Get the top topics filtered by period' do
       tags 'Topics'
+      operationId 'listTopTopics'
       consumes 'application/json'
       parameter name: 'Api-Key', in: :header, type: :string, required: true
       parameter name: 'Api-Username', in: :header, type: :string, required: true
@@ -853,6 +765,7 @@ describe 'topics' do
   path '/t/{id}/notifications.json' do
     post 'Set notification level' do
       tags 'Topics'
+      operationId 'setNotificationLevel'
       consumes 'application/json'
       parameter name: 'Api-Key', in: :header, type: :string, required: true
       parameter name: 'Api-Username', in: :header, type: :string, required: true
@@ -885,6 +798,7 @@ describe 'topics' do
   path '/t/{id}/change-timestamp.json' do
     put 'Update topic timestamp' do
       tags 'Topics'
+      operationId 'updateTopicTimestamp'
       consumes 'application/json'
       parameter name: 'Api-Key', in: :header, type: :string, required: true
       parameter name: 'Api-Username', in: :header, type: :string, required: true
@@ -918,6 +832,7 @@ describe 'topics' do
   path '/t/{id}/timer.json' do
     post 'Create topic timer' do
       tags 'Topics'
+      operationId 'createTopicTimer'
       consumes 'application/json'
       parameter name: 'Api-Key', in: :header, type: :string, required: true
       parameter name: 'Api-Username', in: :header, type: :string, required: true

spec/requests/api/uploads_spec.rb

@@ -15,6 +15,7 @@ describe 'uploads' do
   path '/uploads.json' do
     post 'Creates an upload' do
       tags 'Uploads'
+      operationId 'createUpload'
       consumes 'multipart/form-data'
 
       expected_request_schema = load_spec_schema('upload_create_request')

spec/requests/api/user_badges_spec.rb

@@ -14,6 +14,7 @@ describe 'user_badges' do
 
     get 'List badges for a user' do
       tags 'Badges', 'Users'
+      operationId 'listUserBadges'
       consumes 'application/json'
       expected_request_schema = nil
       parameter name: :username, in: :path, schema: { type: :string }

spec/requests/api/users_spec.rb

@@ -17,6 +17,7 @@ describe 'users' do
 
     post 'Creates a user' do
       tags 'Users'
+      operationId 'createUser'
       consumes 'application/json'
       parameter name: 'Api-Key', in: :header, type: :string, required: true
       parameter name: 'Api-Username', in: :header, type: :string, required: true
@@ -64,6 +65,7 @@ describe 'users' do
 
     get 'Get a single user by username' do
       tags 'Users'
+      operationId 'getUser'
       consumes 'application/json'
       parameter name: 'Api-Key', in: :header, type: :string, required: true
       parameter name: 'Api-Username', in: :header, type: :string, required: true
@@ -83,6 +85,7 @@ describe 'users' do
 
     get 'Get a user by external_id' do
       tags 'Users'
+      operationId 'getUserExternalId'
       consumes 'application/json'
       parameter name: 'Api-Key', in: :header, type: :string, required: true
       parameter name: 'Api-Username', in: :header, type: :string, required: true
@@ -110,6 +113,7 @@ describe 'users' do
 
     get 'Get a user by identity provider external ID' do
       tags 'Users'
+      operationId 'getUserIdentiyProviderExternalId'
       consumes 'application/json'
       parameter name: 'Api-Key', in: :header, type: :string, required: true
       parameter name: 'Api-Username', in: :header, type: :string, required: true
@@ -142,6 +146,7 @@ describe 'users' do
 
     put 'Update avatar' do
       tags 'Users'
+      operationId 'updateAvatar'
       consumes 'application/json'
       expected_request_schema = load_spec_schema('user_update_avatar_request')
 
@@ -172,6 +177,7 @@ describe 'users' do
 
     put 'Update email' do
       tags 'Users'
+      operationId 'updateEmail'
       consumes 'application/json'
       expected_request_schema = load_spec_schema('user_update_email_request')
 
@@ -200,6 +206,7 @@ describe 'users' do
 
     get 'Get a public list of users' do
       tags 'Users'
+      operationId 'listUsersPublic'
       consumes 'application/json'
       expected_request_schema = nil
 
@@ -257,6 +264,7 @@ describe 'users' do
 
     get 'Get a user by id' do
       tags 'Users', 'Admin'
+      operationId 'adminGetUser'
       consumes 'application/json'
       expected_request_schema = nil
 
@@ -279,6 +287,7 @@ describe 'users' do
 
     delete 'Delete a user' do
       tags 'Users', 'Admin'
+      operationId 'deleteUser'
       consumes 'application/json'
       expected_request_schema = load_spec_schema('user_delete_request')
 
@@ -311,6 +320,7 @@ describe 'users' do
   path '/admin/users/{id}/suspend.json' do
     put 'Suspend a user' do
       tags 'Users', 'Admin'
+      operationId 'suspendUser'
       consumes 'application/json'
       expected_request_schema = load_spec_schema('user_suspend_request')
 
@@ -340,6 +350,7 @@ describe 'users' do
   path '/admin/users/{id}/anonymize.json' do
     put 'Anonymize a user' do
       tags 'Users', 'Admin'
+      operationId 'anonymizeUser'
       consumes 'application/json'
       expected_request_schema = nil
 
@@ -365,6 +376,7 @@ describe 'users' do
 
     post 'Log a user out' do
       tags 'Users', 'Admin'
+      operationId 'logOutUser'
       consumes 'application/json'
       expected_request_schema = nil
 
@@ -401,6 +413,7 @@ describe 'users' do
 
     post 'Refresh gravatar' do
       tags 'Users', 'Admin'
+      operationId 'refreshGravatar'
       consumes 'application/json'
       expected_request_schema = nil
 
@@ -427,6 +440,7 @@ describe 'users' do
 
     get 'Get a list of users' do
       tags 'Users', 'Admin'
+      operationId 'adminListUsers'
       consumes 'application/json'
       expected_request_schema = nil
 
@@ -488,6 +502,7 @@ describe 'users' do
 
     get 'Get a list of user actions' do
       tags 'Users'
+      operationId 'listUserActions'
       consumes 'application/json'
       expected_request_schema = nil
 
@@ -516,6 +531,7 @@ describe 'users' do
   path '/session/forgot_password.json' do
     post 'Send password reset email' do
       tags 'Users'
+      operationId 'sendPasswordResetEmail'
       consumes 'application/json'
       expected_request_schema = load_spec_schema('user_password_reset_request')
       parameter name: :params, in: :body, schema: expected_request_schema
@@ -539,6 +555,7 @@ describe 'users' do
   path '/users/password-reset/{token}.json' do
     put 'Change password' do
       tags 'Users'
+      operationId 'changePassword'
       consumes 'application/json'
       expected_request_schema = load_spec_schema('user_password_change_request')
       parameter name: :token, in: :path, type: :string, required: true