Improve OpenAPI spec and deploy it to api.pleroma.social

Too many changes in OpenAPI spec to describe each one, but basically it is tag fixes, bringing consitency to operation summaries and fixing some incorrect information.
2021-02-03 15:38:59 +03:00 · 2021-02-03 15:38:59 +03:00 · 9fcff7851f
commit 9fcff7851f
parent ba40af054c
39 changed files with 334 additions and 229 deletions
--- a/.gitlab-ci.yml
+++ b/.gitlab-ci.yml
@ -34,6 +34,14 @@ build:
  - mix deps.get
  - mix compile --force

+spec-build:
+  stage: test
+  artifacts:
+    paths:
+    - spec.json
+  script:
+  - mix pleroma.openapi_spec spec.json
+
 benchmark:
  stage: benchmark
  when: manual
@ -155,6 +163,17 @@ review_app:
    - (ssh -t dokku@pleroma.online -- certs:add "$CI_ENVIRONMENT_SLUG" /home/dokku/server.crt /home/dokku/server.key) || true
    - git push -f dokku@pleroma.online:$CI_ENVIRONMENT_SLUG $CI_COMMIT_SHA:refs/heads/master

+spec-deploy:
+  stage: deploy
+  only:
+    - develop@pleroma/pleroma
+  image: alpine:latest
+  before_script:
+    - apk add curl
+  script:
+    - curl -X POST -F"token=$API_DOCS_PIPELINE_TRIGGER" -F'ref=master' -F"variables[BRANCH]=$CI_COMMIT_REF_NAME" https://git.pleroma.social/api/v4/projects/1130/trigger/pipeline
+  
+ 
 stop_review_app:
  image: alpine:3.9
  stage: deploy
--- a/lib/mix/tasks/pleroma/openapi_spec.ex
+++ b/lib/mix/tasks/pleroma/openapi_spec.ex
@ -0,0 +1,6 @@
+defmodule Mix.Tasks.Pleroma.OpenapiSpec do
+  def run([path]) do
+    spec = Pleroma.Web.ApiSpec.spec(server_specific: false) |> Jason.encode!()
+    File.write(path, spec)
+  end
+end
--- a/lib/pleroma/web/api_spec.ex
+++ b/lib/pleroma/web/api_spec.ex
@ -11,10 +11,10 @@ defmodule Pleroma.Web.ApiSpec do
  @behaviour OpenApi

  @impl OpenApi
-  def spec do
+  def spec(opts \\ []) do
    %OpenApi{
      servers:
-        if Phoenix.Endpoint.server?(:pleroma, Endpoint) do
+        if opts[:server_specific] do
          [
            # Populate the Server info from a phoenix endpoint
            OpenApiSpex.Server.from_endpoint(Endpoint)
@ -23,9 +23,25 @@ defmodule Pleroma.Web.ApiSpec do
          []
        end,
      info: %OpenApiSpex.Info{
-        title: "Pleroma",
-        description: Application.spec(:pleroma, :description) |> to_string(),
-        version: Application.spec(:pleroma, :vsn) |> to_string()
+        title: "Pleroma API",
+        description: """
+        This is documentation for client Pleroma API. Most of the endpoints and entities come
+        from Mastodon API and have custom extensions on top.
+
+        While this document aims to be a complete guide to the client API Pleroma exposes,
+        the details are still being worked out. Some endpoints may have incomplete or poorly worded documentation.
+        You might want to check the following resources if something is not clear:
+        - [Legacy Pleroma-specific endpoint documentation](https://docs-develop.pleroma.social/backend/development/API/pleroma_api/)
+        - [Mastodon API documentation](https://docs.joinmastodon.org/client/intro/)
+        - [Differences in Mastodon API responses from vanilla Mastodon](https://docs-develop.pleroma.social/backend/development/API/differences_in_mastoapi_responses/)
+
+        Please report such occurences on our [issue tracker](https://git.pleroma.social/pleroma/pleroma/-/issues). Feel free to submit API questions or proposals there too!
+        """,
+        version: Application.spec(:pleroma, :vsn) |> to_string(),
+        extensions: %{
+          # Logo path should be picked so that the path exists both on Pleroma instances and on api.pleroma.social
+          "x-logo": %{"url" => "/static/logo.svg", "altText" => "Pleroma logo"}
+        }
      },
      # populate the paths from a phoenix router
      paths: OpenApiSpex.Paths.from_router(Router),
@ -45,15 +61,73 @@ defmodule Pleroma.Web.ApiSpec do
                authorizationUrl: "/oauth/authorize",
                tokenUrl: "/oauth/token",
                scopes: %{
-                  "read" => "read",
-                  "write" => "write",
-                  "follow" => "follow",
-                  "push" => "push"
+                  # TODO: Document granular scopes
+                  "read" => "Read everything",
+                  "write" => "Write everything",
+                  "follow" => "Manage relationships",
+                  "push" => "Web Push API subscriptions"
                }
              }
            }
          }
        }
+      },
+      extensions: %{
+        # Redoc-specific extension, every time a new tag is added it should be reflected here,
+        # otherwise it won't be shown.
+        "x-tagGroups": [
+          %{
+            "name" => "Accounts",
+            "tags" => ["Account actions", "Retrieve account information", "Scrobbles"]
+          },
+          %{
+            "name" => "Administration",
+            "tags" => [
+              "Chat administration",
+              "Emoji packs",
+              "Frontend managment",
+              "Instance configuration",
+              "Instance documents",
+              "Invites",
+              "MediaProxy cache",
+              "OAuth application managment",
+              "Report managment",
+              "Relays",
+              "Status administration"
+            ]
+          },
+          %{"name" => "Applications", "tags" => ["Applications", "Push subscriptions"]},
+          %{
+            "name" => "Current account",
+            "tags" => [
+              "Account credentials",
+              "Backups",
+              "Blocks and mutes",
+              "Data import",
+              "Domain blocks",
+              "Follow requests",
+              "Mascot",
+              "Markers",
+              "Notifications"
+            ]
+          },
+          %{"name" => "Instance", "tags" => ["Custom emojis"]},
+          %{"name" => "Messaging", "tags" => ["Chats", "Conversations"]},
+          %{
+            "name" => "Statuses",
+            "tags" => [
+              "Emoji reactions",
+              "Lists",
+              "Polls",
+              "Timelines",
+              "Retrieve status information",
+              "Scheduled statuses",
+              "Search",
+              "Status actions"
+            ]
+          },
+          %{"name" => "Miscellaneous", "tags" => ["Reports", "Suggestions"]}
+        ]
      }
    }
    # discover request/response schemas from path specs
--- a/lib/pleroma/web/api_spec/operations/account_operation.ex
+++ b/lib/pleroma/web/api_spec/operations/account_operation.ex
@ -26,7 +26,7 @@ defmodule Pleroma.Web.ApiSpec.AccountOperation do
  @spec create_operation() :: Operation.t()
  def create_operation do
    %Operation{
-      tags: ["accounts"],
+      tags: ["Account credentials"],
      summary: "Register an account",
      description:
        "Creates a user and account records. Returns an account access token for the app that initiated the request. The app should save this token for later, and should wait for the user to confirm their account by clicking a link in their email inbox.",
@ -43,7 +43,7 @@ defmodule Pleroma.Web.ApiSpec.AccountOperation do

  def verify_credentials_operation do
    %Operation{
-      tags: ["accounts"],
+      tags: ["Account credentials"],
      description: "Test to make sure that the user token works.",
      summary: "Verify account credentials",
      operationId: "AccountController.verify_credentials",
@ -56,7 +56,7 @@ defmodule Pleroma.Web.ApiSpec.AccountOperation do

  def update_credentials_operation do
    %Operation{
-      tags: ["accounts"],
+      tags: ["Account credentials"],
      summary: "Update account credentials",
      description: "Update the user's display and preferences.",
      operationId: "AccountController.update_credentials",
@ -71,8 +71,8 @@ defmodule Pleroma.Web.ApiSpec.AccountOperation do

  def relationships_operation do
    %Operation{
-      tags: ["accounts"],
-      summary: "Check relationships to other accounts",
+      tags: ["Retrieve account information"],
+      summary: "Relationship with current account",
      operationId: "AccountController.relationships",
      description: "Find out whether a given account is followed, blocked, muted, etc.",
      security: [%{"oAuth" => ["read:follows"]}],
@ -95,7 +95,7 @@ defmodule Pleroma.Web.ApiSpec.AccountOperation do

  def show_operation do
    %Operation{
-      tags: ["accounts"],
+      tags: ["Retrieve account information"],
      summary: "Account",
      operationId: "AccountController.show",
      description: "View information about a profile.",
@ -110,8 +110,8 @@ defmodule Pleroma.Web.ApiSpec.AccountOperation do

  def statuses_operation do
    %Operation{
-      tags: ["accounts"],
      summary: "Statuses",
+      tags: ["Retrieve account information"],
      operationId: "AccountController.statuses",
      description:
        "Statuses posted to the given account. Public (for public statuses only), or user token + `read:statuses` (for private statuses the user is authorized to see)",
@ -157,7 +157,7 @@ defmodule Pleroma.Web.ApiSpec.AccountOperation do

  def followers_operation do
    %Operation{
-      tags: ["accounts"],
+      tags: ["Retrieve account information"],
      summary: "Followers",
      operationId: "AccountController.followers",
      security: [%{"oAuth" => ["read:accounts"]}],
@ -176,7 +176,7 @@ defmodule Pleroma.Web.ApiSpec.AccountOperation do

  def following_operation do
    %Operation{
-      tags: ["accounts"],
+      tags: ["Retrieve account information"],
      summary: "Following",
      operationId: "AccountController.following",
      security: [%{"oAuth" => ["read:accounts"]}],
@ -193,7 +193,7 @@ defmodule Pleroma.Web.ApiSpec.AccountOperation do

  def lists_operation do
    %Operation{
-      tags: ["accounts"],
+      tags: ["Retrieve account information"],
      summary: "Lists containing this account",
      operationId: "AccountController.lists",
      security: [%{"oAuth" => ["read:lists"]}],
@ -205,7 +205,7 @@ defmodule Pleroma.Web.ApiSpec.AccountOperation do

  def follow_operation do
    %Operation{
-      tags: ["accounts"],
+      tags: ["Account actions"],
      summary: "Follow",
      operationId: "AccountController.follow",
      security: [%{"oAuth" => ["follow", "write:follows"]}],
@ -238,7 +238,7 @@ defmodule Pleroma.Web.ApiSpec.AccountOperation do

  def unfollow_operation do
    %Operation{
-      tags: ["accounts"],
+      tags: ["Account actions"],
      summary: "Unfollow",
      operationId: "AccountController.unfollow",
      security: [%{"oAuth" => ["follow", "write:follows"]}],
@ -254,7 +254,7 @@ defmodule Pleroma.Web.ApiSpec.AccountOperation do

  def mute_operation do
    %Operation{
-      tags: ["accounts"],
+      tags: ["Account actions"],
      summary: "Mute",
      operationId: "AccountController.mute",
      security: [%{"oAuth" => ["follow", "write:mutes"]}],
@ -284,7 +284,7 @@ defmodule Pleroma.Web.ApiSpec.AccountOperation do

  def unmute_operation do
    %Operation{
-      tags: ["accounts"],
+      tags: ["Account actions"],
      summary: "Unmute",
      operationId: "AccountController.unmute",
      security: [%{"oAuth" => ["follow", "write:mutes"]}],
@ -298,7 +298,7 @@ defmodule Pleroma.Web.ApiSpec.AccountOperation do

  def block_operation do
    %Operation{
-      tags: ["accounts"],
+      tags: ["Account actions"],
      summary: "Block",
      operationId: "AccountController.block",
      security: [%{"oAuth" => ["follow", "write:blocks"]}],
@ -313,7 +313,7 @@ defmodule Pleroma.Web.ApiSpec.AccountOperation do

  def unblock_operation do
    %Operation{
-      tags: ["accounts"],
+      tags: ["Account actions"],
      summary: "Unblock",
      operationId: "AccountController.unblock",
      security: [%{"oAuth" => ["follow", "write:blocks"]}],
@ -327,7 +327,7 @@ defmodule Pleroma.Web.ApiSpec.AccountOperation do

  def follow_by_uri_operation do
    %Operation{
-      tags: ["accounts"],
+      tags: ["Account actions"],
      summary: "Follow by URI",
      operationId: "AccountController.follows",
      security: [%{"oAuth" => ["follow", "write:follows"]}],
@ -342,8 +342,8 @@ defmodule Pleroma.Web.ApiSpec.AccountOperation do

  def mutes_operation do
    %Operation{
-      tags: ["accounts"],
-      summary: "Muted accounts",
+      tags: ["Blocks and mutes"],
+      summary: "Retrieve list of mutes",
      operationId: "AccountController.mutes",
      description: "Accounts the user has muted.",
      security: [%{"oAuth" => ["follow", "read:mutes"]}],
@ -356,8 +356,8 @@ defmodule Pleroma.Web.ApiSpec.AccountOperation do

  def blocks_operation do
    %Operation{
-      tags: ["accounts"],
-      summary: "Blocked users",
+      tags: ["Blocks and mutes"],
+      summary: "Retrieve list of blocks",
      operationId: "AccountController.blocks",
      description: "View your blocks. See also accounts/:id/{block,unblock}",
      security: [%{"oAuth" => ["read:blocks"]}],
@ -370,7 +370,7 @@ defmodule Pleroma.Web.ApiSpec.AccountOperation do

  def endorsements_operation do
    %Operation{
-      tags: ["accounts"],
+      tags: ["Retrieve account information"],
      summary: "Endorsements",
      operationId: "AccountController.endorsements",
      description: "Not implemented",
@ -383,7 +383,7 @@ defmodule Pleroma.Web.ApiSpec.AccountOperation do

  def identity_proofs_operation do
    %Operation{
-      tags: ["accounts"],
+      tags: ["Retrieve account information"],
      summary: "Identity proofs",
      operationId: "AccountController.identity_proofs",
      # Validators complains about unused path params otherwise
--- a/lib/pleroma/web/api_spec/operations/admin/chat_operation.ex
+++ b/lib/pleroma/web/api_spec/operations/admin/chat_operation.ex
@ -16,7 +16,7 @@ defmodule Pleroma.Web.ApiSpec.Admin.ChatOperation do

  def delete_message_operation do
    %Operation{
-      tags: ["admin", "chat"],
+      tags: ["Chat administration"],
      summary: "Delete an individual chat message",
      operationId: "AdminAPI.ChatController.delete_message",
      parameters: [
@ -41,8 +41,8 @@ defmodule Pleroma.Web.ApiSpec.Admin.ChatOperation do

  def messages_operation do
    %Operation{
-      tags: ["admin", "chat"],
-      summary: "Get the most recent messages of the chat",
+      tags: ["Chat administration"],
+      summary: "Get chat's messages",
      operationId: "AdminAPI.ChatController.messages",
      parameters:
        [Operation.parameter(:id, :path, :string, "The ID of the Chat")] ++
@ -65,7 +65,7 @@ defmodule Pleroma.Web.ApiSpec.Admin.ChatOperation do

  def show_operation do
    %Operation{
-      tags: ["chat"],
+      tags: ["Chat administration"],
      summary: "Create a chat",
      operationId: "AdminAPI.ChatController.show",
      parameters: [
--- a/lib/pleroma/web/api_spec/operations/admin/config_operation.ex
+++ b/lib/pleroma/web/api_spec/operations/admin/config_operation.ex
@ -16,8 +16,8 @@ defmodule Pleroma.Web.ApiSpec.Admin.ConfigOperation do

  def show_operation do
    %Operation{
-      tags: ["Admin", "Config"],
-      summary: "Get list of merged default settings with saved in database",
+      tags: ["Instance configuration"],
+      summary: "Retrieve instance configuration",
      operationId: "AdminAPI.ConfigController.show",
      parameters: [
        Operation.parameter(
@ -38,8 +38,8 @@ defmodule Pleroma.Web.ApiSpec.Admin.ConfigOperation do

  def update_operation do
    %Operation{
-      tags: ["Admin", "Config"],
-      summary: "Update config settings",
+      tags: ["Instance configuration"],
+      summary: "Update instance configuration",
      operationId: "AdminAPI.ConfigController.update",
      security: [%{"oAuth" => ["write"]}],
      parameters: admin_api_params(),
@ -71,8 +71,8 @@ defmodule Pleroma.Web.ApiSpec.Admin.ConfigOperation do

  def descriptions_operation do
    %Operation{
-      tags: ["Admin", "Config"],
-      summary: "Get JSON with config descriptions.",
+      tags: ["Instance configuration"],
+      summary: "Retrieve config description",
      operationId: "AdminAPI.ConfigController.descriptions",
      security: [%{"oAuth" => ["read"]}],
      parameters: admin_api_params(),
--- a/lib/pleroma/web/api_spec/operations/admin/frontend_operation.ex
+++ b/lib/pleroma/web/api_spec/operations/admin/frontend_operation.ex
@ -16,8 +16,8 @@ defmodule Pleroma.Web.ApiSpec.Admin.FrontendOperation do

  def index_operation do
    %Operation{
-      tags: ["Admin", "Reports"],
-      summary: "Get a list of available frontends",
+      tags: ["Frontend managment"],
+      summary: "Retrieve a list of available frontends",
      operationId: "AdminAPI.FrontendController.index",
      security: [%{"oAuth" => ["read"]}],
      responses: %{
@ -29,7 +29,7 @@ defmodule Pleroma.Web.ApiSpec.Admin.FrontendOperation do

  def install_operation do
    %Operation{
-      tags: ["Admin", "Reports"],
+      tags: ["Frontend managment"],
      summary: "Install a frontend",
      operationId: "AdminAPI.FrontendController.install",
      security: [%{"oAuth" => ["read"]}],
--- a/lib/pleroma/web/api_spec/operations/admin/instance_document_operation.ex
+++ b/lib/pleroma/web/api_spec/operations/admin/instance_document_operation.ex
@ -15,8 +15,8 @@ defmodule Pleroma.Web.ApiSpec.Admin.InstanceDocumentOperation do

  def show_operation do
    %Operation{
-      tags: ["Admin", "InstanceDocument"],
-      summary: "Get the instance document",
+      tags: ["Instance documents"],
+      summary: "Retrieve an instance document",
      operationId: "AdminAPI.InstanceDocumentController.show",
      security: [%{"oAuth" => ["read"]}],
      parameters: [
@ -36,8 +36,8 @@ defmodule Pleroma.Web.ApiSpec.Admin.InstanceDocumentOperation do

  def update_operation do
    %Operation{
-      tags: ["Admin", "InstanceDocument"],
-      summary: "Update the instance document",
+      tags: ["Instance documents"],
+      summary: "Update an instance document",
      operationId: "AdminAPI.InstanceDocumentController.update",
      security: [%{"oAuth" => ["write"]}],
      requestBody: Helpers.request_body("Parameters", update_request()),
@ -74,8 +74,8 @@ defmodule Pleroma.Web.ApiSpec.Admin.InstanceDocumentOperation do

  def delete_operation do
    %Operation{
-      tags: ["Admin", "InstanceDocument"],
-      summary: "Get the instance document",
+      tags: ["Instance documents"],
+      summary: "Delete an instance document",
      operationId: "AdminAPI.InstanceDocumentController.delete",
      security: [%{"oAuth" => ["write"]}],
      parameters: [
--- a/lib/pleroma/web/api_spec/operations/admin/invite_operation.ex
+++ b/lib/pleroma/web/api_spec/operations/admin/invite_operation.ex
@ -16,7 +16,7 @@ defmodule Pleroma.Web.ApiSpec.Admin.InviteOperation do

  def index_operation do
    %Operation{
-      tags: ["Admin", "Invites"],
+      tags: ["Invites"],
      summary: "Get a list of generated invites",
      operationId: "AdminAPI.InviteController.index",
      security: [%{"oAuth" => ["read:invites"]}],
@ -48,7 +48,7 @@ defmodule Pleroma.Web.ApiSpec.Admin.InviteOperation do

  def create_operation do
    %Operation{
-      tags: ["Admin", "Invites"],
+      tags: ["Invites"],
      summary: "Create an account registration invite token",
      operationId: "AdminAPI.InviteController.create",
      security: [%{"oAuth" => ["write:invites"]}],
@ -69,7 +69,7 @@ defmodule Pleroma.Web.ApiSpec.Admin.InviteOperation do

  def revoke_operation do
    %Operation{
-      tags: ["Admin", "Invites"],
+      tags: ["Invites"],
      summary: "Revoke invite by token",
      operationId: "AdminAPI.InviteController.revoke",
      security: [%{"oAuth" => ["write:invites"]}],
@ -96,7 +96,7 @@ defmodule Pleroma.Web.ApiSpec.Admin.InviteOperation do

  def email_operation do
    %Operation{
-      tags: ["Admin", "Invites"],
+      tags: ["Invites"],
      summary: "Sends registration invite via email",
      operationId: "AdminAPI.InviteController.email",
      security: [%{"oAuth" => ["write:invites"]}],
--- a/lib/pleroma/web/api_spec/operations/admin/media_proxy_cache_operation.ex
+++ b/lib/pleroma/web/api_spec/operations/admin/media_proxy_cache_operation.ex
@ -16,8 +16,8 @@ defmodule Pleroma.Web.ApiSpec.Admin.MediaProxyCacheOperation do

  def index_operation do
    %Operation{
-      tags: ["Admin", "MediaProxyCache"],
-      summary: "Fetch a paginated list of all banned MediaProxy URLs in Cachex",
+      tags: ["MediaProxy cache"],
+      summary: "Retrieve a list of banned MediaProxy URLs",
      operationId: "AdminAPI.MediaProxyCacheController.index",
      security: [%{"oAuth" => ["read:media_proxy_caches"]}],
      parameters: [
@ -44,7 +44,7 @@ defmodule Pleroma.Web.ApiSpec.Admin.MediaProxyCacheOperation do
      responses: %{
        200 =>
          Operation.response(
-            "Array of banned MediaProxy URLs in Cachex",
+            "Array of MediaProxy URLs",
            "application/json",
            %Schema{
              type: :object,
@ -68,8 +68,8 @@ defmodule Pleroma.Web.ApiSpec.Admin.MediaProxyCacheOperation do

  def delete_operation do
    %Operation{
-      tags: ["Admin", "MediaProxyCache"],
-      summary: "Remove a banned MediaProxy URL from Cachex",
+      tags: ["MediaProxy cache"],
+      summary: "Remove a banned MediaProxy URL",
      operationId: "AdminAPI.MediaProxyCacheController.delete",
      security: [%{"oAuth" => ["write:media_proxy_caches"]}],
      parameters: admin_api_params(),
@ -94,8 +94,8 @@ defmodule Pleroma.Web.ApiSpec.Admin.MediaProxyCacheOperation do

  def purge_operation do
    %Operation{
-      tags: ["Admin", "MediaProxyCache"],
-      summary: "Purge and optionally ban a MediaProxy URL",
+      tags: ["MediaProxy cache"],
+      summary: "Purge a URL from MediaProxy cache and optionally ban it",
      operationId: "AdminAPI.MediaProxyCacheController.purge",
      security: [%{"oAuth" => ["write:media_proxy_caches"]}],
      parameters: admin_api_params(),
--- a/lib/pleroma/web/api_spec/operations/admin/o_auth_app_operation.ex
+++ b/lib/pleroma/web/api_spec/operations/admin/o_auth_app_operation.ex
@ -16,8 +16,8 @@ defmodule Pleroma.Web.ApiSpec.Admin.OAuthAppOperation do

  def index_operation do
    %Operation{
-      summary: "List OAuth apps",
-      tags: ["Admin", "oAuth Apps"],
+      summary: "Retrieve a list of OAuth applications",
+      tags: ["OAuth application managment"],
      operationId: "AdminAPI.OAuthAppController.index",
      security: [%{"oAuth" => ["write"]}],
      parameters: [
@ -69,8 +69,8 @@ defmodule Pleroma.Web.ApiSpec.Admin.OAuthAppOperation do

  def create_operation do
    %Operation{
-      tags: ["Admin", "oAuth Apps"],
-      summary: "Create OAuth App",
+      tags: ["OAuth application managment"],
+      summary: "Create an OAuth application",
      operationId: "AdminAPI.OAuthAppController.create",
      requestBody: request_body("Parameters", create_request()),
      parameters: admin_api_params(),
@ -84,8 +84,8 @@ defmodule Pleroma.Web.ApiSpec.Admin.OAuthAppOperation do

  def update_operation do
    %Operation{
-      tags: ["Admin", "oAuth Apps"],
-      summary: "Update OAuth App",
+      tags: ["OAuth application managment"],
+      summary: "Update OAuth application",
      operationId: "AdminAPI.OAuthAppController.update",
      parameters: [id_param() | admin_api_params()],
      security: [%{"oAuth" => ["write"]}],
@ -102,8 +102,8 @@ defmodule Pleroma.Web.ApiSpec.Admin.OAuthAppOperation do

  def delete_operation do
    %Operation{
-      tags: ["Admin", "oAuth Apps"],
-      summary: "Delete OAuth App",
+      tags: ["OAuth application managment"],
+      summary: "Delete OAuth application",
      operationId: "AdminAPI.OAuthAppController.delete",
      parameters: [id_param() | admin_api_params()],
      security: [%{"oAuth" => ["write"]}],
--- a/lib/pleroma/web/api_spec/operations/admin/relay_operation.ex
+++ b/lib/pleroma/web/api_spec/operations/admin/relay_operation.ex
@ -15,8 +15,8 @@ defmodule Pleroma.Web.ApiSpec.Admin.RelayOperation do

  def index_operation do
    %Operation{
-      tags: ["Admin", "Relays"],
-      summary: "List Relays",
+      tags: ["Relays"],
+      summary: "Retrieve a list of relays",
      operationId: "AdminAPI.RelayController.index",
      security: [%{"oAuth" => ["read"]}],
      parameters: admin_api_params(),
@ -37,8 +37,8 @@ defmodule Pleroma.Web.ApiSpec.Admin.RelayOperation do

  def follow_operation do
    %Operation{
-      tags: ["Admin", "Relays"],
-      summary: "Follow a Relay",
+      tags: ["Relays"],
+      summary: "Follow a relay",
      operationId: "AdminAPI.RelayController.follow",
      security: [%{"oAuth" => ["write:follows"]}],
      parameters: admin_api_params(),
@ -51,8 +51,8 @@ defmodule Pleroma.Web.ApiSpec.Admin.RelayOperation do

  def unfollow_operation do
    %Operation{
-      tags: ["Admin", "Relays"],
-      summary: "Unfollow a Relay",
+      tags: ["Relays"],
+      summary: "Unfollow a relay",
      operationId: "AdminAPI.RelayController.unfollow",
      security: [%{"oAuth" => ["write:follows"]}],
      parameters: admin_api_params(),
--- a/lib/pleroma/web/api_spec/operations/admin/report_operation.ex
+++ b/lib/pleroma/web/api_spec/operations/admin/report_operation.ex
@ -19,8 +19,8 @@ defmodule Pleroma.Web.ApiSpec.Admin.ReportOperation do

  def index_operation do
    %Operation{
-      tags: ["Admin", "Reports"],
-      summary: "Get a list of reports",
+      tags: ["Report managment"],
+      summary: "Retrieve a list of reports",
      operationId: "AdminAPI.ReportController.index",
      security: [%{"oAuth" => ["read:reports"]}],
      parameters: [
@ -69,8 +69,8 @@ defmodule Pleroma.Web.ApiSpec.Admin.ReportOperation do

  def show_operation do
    %Operation{
-      tags: ["Admin", "Reports"],
-      summary: "Get an individual report",
+      tags: ["Report managment"],
+      summary: "Retrieve a report",
      operationId: "AdminAPI.ReportController.show",
      parameters: [id_param() | admin_api_params()],
      security: [%{"oAuth" => ["read:reports"]}],
@ -83,8 +83,8 @@ defmodule Pleroma.Web.ApiSpec.Admin.ReportOperation do

  def update_operation do
    %Operation{
-      tags: ["Admin", "Reports"],
-      summary: "Change the state of one or multiple reports",
+      tags: ["Report managment"],
+      summary: "Change state of specified reports",
      operationId: "AdminAPI.ReportController.update",
      security: [%{"oAuth" => ["write:reports"]}],
      parameters: admin_api_params(),
@ -99,8 +99,8 @@ defmodule Pleroma.Web.ApiSpec.Admin.ReportOperation do

  def notes_create_operation do
    %Operation{
-      tags: ["Admin", "Reports"],
-      summary: "Create report note",
+      tags: ["Report managment"],
+      summary: "Add a note to the report",
      operationId: "AdminAPI.ReportController.notes_create",
      parameters: [id_param() | admin_api_params()],
      requestBody:
@ -120,8 +120,8 @@ defmodule Pleroma.Web.ApiSpec.Admin.ReportOperation do

  def notes_delete_operation do
    %Operation{
-      tags: ["Admin", "Reports"],
-      summary: "Delete report note",
+      tags: ["Report managment"],
+      summary: "Delete note attached to the report",
      operationId: "AdminAPI.ReportController.notes_delete",
      parameters: [
        Operation.parameter(:report_id, :path, :string, "Report ID"),
--- a/lib/pleroma/web/api_spec/operations/admin/status_operation.ex
+++ b/lib/pleroma/web/api_spec/operations/admin/status_operation.ex
@ -21,8 +21,9 @@ defmodule Pleroma.Web.ApiSpec.Admin.StatusOperation do

  def index_operation do
    %Operation{
-      tags: ["Admin", "Statuses"],
+      tags: ["Status administration"],
      operationId: "AdminAPI.StatusController.index",
+      summary: "Get all statuses",
      security: [%{"oAuth" => ["read:statuses"]}],
      parameters: [
        Operation.parameter(
@ -69,8 +70,8 @@ defmodule Pleroma.Web.ApiSpec.Admin.StatusOperation do

  def show_operation do
    %Operation{
-      tags: ["Admin", "Statuses"],
-      summary: "Show Status",
+      tags: ["Status adminitration)"],
+      summary: "Get status",
      operationId: "AdminAPI.StatusController.show",
      parameters: [id_param() | admin_api_params()],
      security: [%{"oAuth" => ["read:statuses"]}],
@ -83,8 +84,8 @@ defmodule Pleroma.Web.ApiSpec.Admin.StatusOperation do

  def update_operation do
    %Operation{
-      tags: ["Admin", "Statuses"],
-      summary: "Change the scope of an individual reported status",
+      tags: ["Status adminitration)"],
+      summary: "Change the scope of a status",
      operationId: "AdminAPI.StatusController.update",
      parameters: [id_param() | admin_api_params()],
      security: [%{"oAuth" => ["write:statuses"]}],
@ -98,8 +99,8 @@ defmodule Pleroma.Web.ApiSpec.Admin.StatusOperation do

  def delete_operation do
    %Operation{
-      tags: ["Admin", "Statuses"],
-      summary: "Delete an individual reported status",
+      tags: ["Status adminitration)"],
+      summary: "Delete status",
      operationId: "AdminAPI.StatusController.delete",
      parameters: [id_param() | admin_api_params()],
      security: [%{"oAuth" => ["write:statuses"]}],
--- a/lib/pleroma/web/api_spec/operations/app_operation.ex
+++ b/lib/pleroma/web/api_spec/operations/app_operation.ex
@ -16,7 +16,7 @@ defmodule Pleroma.Web.ApiSpec.AppOperation do
  @spec create_operation() :: Operation.t()
  def create_operation do
    %Operation{
-      tags: ["apps"],
+      tags: ["Applications"],
      summary: "Create an application",
      description: "Create a new application to obtain OAuth2 credentials",
      operationId: "AppController.create",
@ -45,8 +45,8 @@ defmodule Pleroma.Web.ApiSpec.AppOperation do

  def verify_credentials_operation do
    %Operation{
-      tags: ["apps"],
-      summary: "Verify your app works",
+      tags: ["Applications"],
+      summary: "Verify the application works",
      description: "Confirm that the app's OAuth2 credentials work.",
      operationId: "AppController.verify_credentials",
      security: [%{"oAuth" => ["read"]}],
--- a/lib/pleroma/web/api_spec/operations/chat_operation.ex
+++ b/lib/pleroma/web/api_spec/operations/chat_operation.ex
@ -20,7 +20,7 @@ defmodule Pleroma.Web.ApiSpec.ChatOperation do

  def mark_as_read_operation do
    %Operation{
-      tags: ["chat"],
+      tags: ["Chats"],
      summary: "Mark all messages in the chat as read",
      operationId: "ChatController.mark_as_read",
      parameters: [Operation.parameter(:id, :path, :string, "The ID of the Chat")],
@ -43,8 +43,8 @@ defmodule Pleroma.Web.ApiSpec.ChatOperation do

  def mark_message_as_read_operation do
    %Operation{
-      tags: ["chat"],
-      summary: "Mark one message in the chat as read",
+      tags: ["Chats"],
+      summary: "Mark a message as read",
      operationId: "ChatController.mark_message_as_read",
      parameters: [
        Operation.parameter(:id, :path, :string, "The ID of the Chat"),
@ -68,8 +68,8 @@ defmodule Pleroma.Web.ApiSpec.ChatOperation do

  def show_operation do
    %Operation{
-      tags: ["chat"],
-      summary: "Create a chat",
+      tags: ["Chats"],
+      summary: "Retrieve a chat",
      operationId: "ChatController.show",
      parameters: [
        Operation.parameter(
@ -99,7 +99,7 @@ defmodule Pleroma.Web.ApiSpec.ChatOperation do

  def create_operation do
    %Operation{
-      tags: ["chat"],
+      tags: ["Chats"],
      summary: "Create a chat",
      operationId: "ChatController.create",
      parameters: [
@ -130,8 +130,8 @@ defmodule Pleroma.Web.ApiSpec.ChatOperation do

  def index_operation do
    %Operation{
-      tags: ["chat"],
-      summary: "Get a list of chats that you participated in",
+      tags: ["Chats"],
+      summary: "Retrieve list of chats",
      operationId: "ChatController.index",
      parameters: [
        Operation.parameter(:with_muted, :query, BooleanLike, "Include chats from muted users")
@ -150,8 +150,8 @@ defmodule Pleroma.Web.ApiSpec.ChatOperation do

  def messages_operation do
    %Operation{
-      tags: ["chat"],
-      summary: "Get the most recent messages of the chat",
+      tags: ["Chats"],
+      summary: "Retrieve chat's messages",
      operationId: "ChatController.messages",
      parameters:
        [Operation.parameter(:id, :path, :string, "The ID of the Chat")] ++
@ -175,7 +175,7 @@ defmodule Pleroma.Web.ApiSpec.ChatOperation do

  def post_chat_message_operation do
    %Operation{
-      tags: ["chat"],
+      tags: ["Chats"],
      summary: "Post a message to the chat",
      operationId: "ChatController.post_chat_message",
      parameters: [
@ -202,8 +202,8 @@ defmodule Pleroma.Web.ApiSpec.ChatOperation do

  def delete_message_operation do
    %Operation{
-      tags: ["chat"],
-      summary: "delete_message",
+      tags: ["Chats"],
+      summary: "Delete message",
      operationId: "ChatController.delete_message",
      parameters: [
        Operation.parameter(:id, :path, :string, "The ID of the Chat"),
--- a/lib/pleroma/web/api_spec/operations/conversation_operation.ex
+++ b/lib/pleroma/web/api_spec/operations/conversation_operation.ex
@ -18,7 +18,7 @@ defmodule Pleroma.Web.ApiSpec.ConversationOperation do
  def index_operation do
    %Operation{
      tags: ["Conversations"],
-      summary: "Show conversation",
+      summary: "List of conversations",
      security: [%{"oAuth" => ["read:statuses"]}],
      operationId: "ConversationController.index",
      parameters: [
@ -44,7 +44,7 @@ defmodule Pleroma.Web.ApiSpec.ConversationOperation do
  def mark_as_read_operation do
    %Operation{
      tags: ["Conversations"],
-      summary: "Mark as read",
+      summary: "Mark conversation as read",
      operationId: "ConversationController.mark_as_read",
      parameters: [
        Operation.parameter(:id, :path, :string, "Conversation ID",
--- a/lib/pleroma/web/api_spec/operations/custom_emoji_operation.ex
+++ b/lib/pleroma/web/api_spec/operations/custom_emoji_operation.ex
@ -14,8 +14,8 @@ defmodule Pleroma.Web.ApiSpec.CustomEmojiOperation do

  def index_operation do
    %Operation{
-      tags: ["custom_emojis"],
-      summary: "List custom custom emojis",
+      tags: ["Custom emojis"],
+      summary: "Retrieve a list of custom emojis",
      description: "Returns custom emojis that are available on the server.",
      operationId: "CustomEmojiController.index",
      responses: %{
--- a/lib/pleroma/web/api_spec/operations/domain_block_operation.ex
+++ b/lib/pleroma/web/api_spec/operations/domain_block_operation.ex
@ -14,9 +14,8 @@ defmodule Pleroma.Web.ApiSpec.DomainBlockOperation do

  def index_operation do
    %Operation{
-      tags: ["domain_blocks"],
-      summary: "Fetch domain blocks",
-      description: "View domains the user has blocked.",
+      tags: ["Domain blocks"],
+      summary: "Retrieve a list of blocked domains",
      security: [%{"oAuth" => ["follow", "read:blocks"]}],
      operationId: "DomainBlockController.index",
      responses: %{
@ -34,7 +33,7 @@ defmodule Pleroma.Web.ApiSpec.DomainBlockOperation do
  # Supporting domain query parameter is deprecated in Mastodon API
  def create_operation do
    %Operation{
-      tags: ["domain_blocks"],
+      tags: ["Domain blocks"],
      summary: "Block a domain",
      description: """
      Block a domain to:
@ -55,7 +54,7 @@ defmodule Pleroma.Web.ApiSpec.DomainBlockOperation do
  # Supporting domain query parameter is deprecated in Mastodon API
  def delete_operation do
    %Operation{
-      tags: ["domain_blocks"],
+      tags: ["Domain blocks"],
      summary: "Unblock a domain",
      description: "Remove a domain block, if it exists in the user's array of blocked domains.",
      operationId: "DomainBlockController.delete",
--- a/lib/pleroma/web/api_spec/operations/emoji_reaction_operation.ex
+++ b/lib/pleroma/web/api_spec/operations/emoji_reaction_operation.ex
@ -17,7 +17,7 @@ defmodule Pleroma.Web.ApiSpec.EmojiReactionOperation do

  def index_operation do
    %Operation{
-      tags: ["Emoji Reactions"],
+      tags: ["Emoji reactions"],
      summary:
        "Get an object of emoji to account mappings with accounts that reacted to the post",
      parameters: [
@ -42,7 +42,7 @@ defmodule Pleroma.Web.ApiSpec.EmojiReactionOperation do

  def create_operation do
    %Operation{
-      tags: ["Emoji Reactions"],
+      tags: ["Emoji reactions"],
      summary: "React to a post with a unicode emoji",
      parameters: [
        Operation.parameter(:id, :path, FlakeID, "Status ID", required: true),
@ -61,7 +61,7 @@ defmodule Pleroma.Web.ApiSpec.EmojiReactionOperation do

  def delete_operation do
    %Operation{
-      tags: ["Emoji Reactions"],
+      tags: ["Emoji reactions"],
      summary: "Remove a reaction to a post with a unicode emoji",
      parameters: [
        Operation.parameter(:id, :path, FlakeID, "Status ID", required: true),
@ -78,7 +78,7 @@ defmodule Pleroma.Web.ApiSpec.EmojiReactionOperation do
  end

  defp array_of_reactions_response do
-    Operation.response("Array of Emoji Reactions", "application/json", %Schema{
+    Operation.response("Array of Emoji reactions", "application/json", %Schema{
      type: :array,
      items: emoji_reaction(),
      example: [emoji_reaction().example]
--- a/lib/pleroma/web/api_spec/operations/filter_operation.ex
+++ b/lib/pleroma/web/api_spec/operations/filter_operation.ex
@ -15,8 +15,8 @@ defmodule Pleroma.Web.ApiSpec.FilterOperation do

  def index_operation do
    %Operation{
-      tags: ["apps"],
-      summary: "View all filters",
+      tags: ["Filters"],
+      summary: "All filters",
      operationId: "FilterController.index",
      security: [%{"oAuth" => ["read:filters"]}],
      responses: %{
@ -27,7 +27,7 @@ defmodule Pleroma.Web.ApiSpec.FilterOperation do

  def create_operation do
    %Operation{
-      tags: ["apps"],
+      tags: ["Filters"],
      summary: "Create a filter",
      operationId: "FilterController.create",
      requestBody: Helpers.request_body("Parameters", create_request(), required: true),
@ -38,8 +38,8 @@ defmodule Pleroma.Web.ApiSpec.FilterOperation do

  def show_operation do
    %Operation{
-      tags: ["apps"],
-      summary: "View all filters",
+      tags: ["Filters"],
+      summary: "Filter",
      parameters: [id_param()],
      operationId: "FilterController.show",
      security: [%{"oAuth" => ["read:filters"]}],
@ -51,7 +51,7 @@ defmodule Pleroma.Web.ApiSpec.FilterOperation do

  def update_operation do
    %Operation{
-      tags: ["apps"],
+      tags: ["Filters"],
      summary: "Update a filter",
      parameters: [id_param()],
      operationId: "FilterController.update",
@ -65,7 +65,7 @@ defmodule Pleroma.Web.ApiSpec.FilterOperation do

  def delete_operation do
    %Operation{
-      tags: ["apps"],
+      tags: ["Filters"],
      summary: "Remove a filter",
      parameters: [id_param()],
      operationId: "FilterController.delete",
--- a/lib/pleroma/web/api_spec/operations/follow_request_operation.ex
+++ b/lib/pleroma/web/api_spec/operations/follow_request_operation.ex
@ -15,8 +15,8 @@ defmodule Pleroma.Web.ApiSpec.FollowRequestOperation do

  def index_operation do
    %Operation{
-      tags: ["Follow Requests"],
-      summary: "Pending Follows",
+      tags: ["Follow requests"],
+      summary: "Retrieve follow requests",
      security: [%{"oAuth" => ["read:follows", "follow"]}],
      operationId: "FollowRequestController.index",
      responses: %{
@ -32,8 +32,8 @@ defmodule Pleroma.Web.ApiSpec.FollowRequestOperation do

  def authorize_operation do
    %Operation{
-      tags: ["Follow Requests"],
-      summary: "Accept Follow",
+      tags: ["Follow requests"],
+      summary: "Accept follow request",
      operationId: "FollowRequestController.authorize",
      parameters: [id_param()],
      security: [%{"oAuth" => ["follow", "write:follows"]}],
@ -45,8 +45,8 @@ defmodule Pleroma.Web.ApiSpec.FollowRequestOperation do

  def reject_operation do
    %Operation{
-      tags: ["Follow Requests"],
-      summary: "Reject Follow",
+      tags: ["Follow requests"],
+      summary: "Reject follow request",
      operationId: "FollowRequestController.reject",
      parameters: [id_param()],
      security: [%{"oAuth" => ["follow", "write:follows"]}],
--- a/lib/pleroma/web/api_spec/operations/instance_operation.ex
+++ b/lib/pleroma/web/api_spec/operations/instance_operation.ex
@ -14,7 +14,7 @@ defmodule Pleroma.Web.ApiSpec.InstanceOperation do
  def show_operation do
    %Operation{
      tags: ["Instance"],
-      summary: "Fetch instance",
+      summary: "Retrieve instance information",
      description: "Information about the server",
      operationId: "InstanceController.show",
      responses: %{
@ -26,7 +26,7 @@ defmodule Pleroma.Web.ApiSpec.InstanceOperation do
  def peers_operation do
    %Operation{
      tags: ["Instance"],
-      summary: "List of known hosts",
+      summary: "Retrieve list of known instances",
      operationId: "InstanceController.peers",
      responses: %{
        200 => Operation.response("Array of domains", "application/json", array_of_domains())
--- a/lib/pleroma/web/api_spec/operations/list_operation.ex
+++ b/lib/pleroma/web/api_spec/operations/list_operation.ex
@ -20,7 +20,7 @@ defmodule Pleroma.Web.ApiSpec.ListOperation do
  def index_operation do
    %Operation{
      tags: ["Lists"],
-      summary: "Show user's lists",
+      summary: "Retrieve a list of lists",
      description: "Fetch all lists that the user owns",
      security: [%{"oAuth" => ["read:lists"]}],
      operationId: "ListController.index",
@ -49,7 +49,7 @@ defmodule Pleroma.Web.ApiSpec.ListOperation do
  def show_operation do
    %Operation{
      tags: ["Lists"],
-      summary: "Show a single list",
+      summary: "Retrieve a list",
      description: "Fetch the list with the given ID. Used for verifying the title of a list.",
      operationId: "ListController.show",
      parameters: [id_param()],
@ -93,7 +93,7 @@ defmodule Pleroma.Web.ApiSpec.ListOperation do
  def list_accounts_operation do
    %Operation{
      tags: ["Lists"],
-      summary: "View accounts in list",
+      summary: "Retrieve accounts in list",
      operationId: "ListController.list_accounts",
      parameters: [id_param()],
      security: [%{"oAuth" => ["read:lists"]}],
--- a/lib/pleroma/web/api_spec/operations/media_operation.ex
+++ b/lib/pleroma/web/api_spec/operations/media_operation.ex
@ -16,7 +16,7 @@ defmodule Pleroma.Web.ApiSpec.MediaOperation do

  def create_operation do
    %Operation{
-      tags: ["media"],
+      tags: ["Media attachments"],
      summary: "Upload media as attachment",
      description: "Creates an attachment to be used with a new status.",
      operationId: "MediaController.create",
@ -56,8 +56,8 @@ defmodule Pleroma.Web.ApiSpec.MediaOperation do

  def update_operation do
    %Operation{
-      tags: ["media"],
-      summary: "Upload media as attachment",
+      tags: ["Media attachments"],
+      summary: "Update attachment",
      description: "Creates an attachment to be used with a new status.",
      operationId: "MediaController.update",
      security: [%{"oAuth" => ["write:media"]}],
@ -97,8 +97,8 @@ defmodule Pleroma.Web.ApiSpec.MediaOperation do

  def show_operation do
    %Operation{
-      tags: ["media"],
-      summary: "Show Uploaded media attachment",
+      tags: ["Media attachments"],
+      summary: "Attachment",
      operationId: "MediaController.show",
      parameters: [id_param()],
      security: [%{"oAuth" => ["read:media"]}],
@ -112,8 +112,8 @@ defmodule Pleroma.Web.ApiSpec.MediaOperation do

  def create2_operation do
    %Operation{
-      tags: ["media"],
-      summary: "Upload media as attachment",
+      tags: ["Media attachments"],
+      summary: "Upload media as attachment (v2)",
      description: "Creates an attachment to be used with a new status.",
      operationId: "MediaController.create2",
      security: [%{"oAuth" => ["write:media"]}],
--- a/lib/pleroma/web/api_spec/operations/notification_operation.ex
+++ b/lib/pleroma/web/api_spec/operations/notification_operation.ex
@ -22,7 +22,7 @@ defmodule Pleroma.Web.ApiSpec.NotificationOperation do
  def index_operation do
    %Operation{
      tags: ["Notifications"],
-      summary: "Get all notifications",
+      summary: "Retrieve a list of notifications",
      description:
        "Notifications concerning the user. This API returns Link headers containing links to the next/previous page. However, the links can also be constructed dynamically using query params and `id` values.",
      operationId: "NotificationController.index",
@ -74,7 +74,7 @@ defmodule Pleroma.Web.ApiSpec.NotificationOperation do
  def show_operation do
    %Operation{
      tags: ["Notifications"],
-      summary: "Get a single notification",
+      summary: "Retrieve a notification",
      description: "View information about a notification with a given ID.",
      operationId: "NotificationController.show",
      security: [%{"oAuth" => ["read:notifications"]}],
@ -99,7 +99,7 @@ defmodule Pleroma.Web.ApiSpec.NotificationOperation do
  def dismiss_operation do
    %Operation{
      tags: ["Notifications"],
-      summary: "Dismiss a single notification",
+      summary: "Dismiss a notification",
      description: "Clear a single notification from the server.",
      operationId: "NotificationController.dismiss",
      parameters: [id_param()],
--- a/lib/pleroma/web/api_spec/operations/pleroma_account_operation.ex
+++ b/lib/pleroma/web/api_spec/operations/pleroma_account_operation.ex
@ -18,8 +18,9 @@ defmodule Pleroma.Web.ApiSpec.PleromaAccountOperation do

  def confirmation_resend_operation do
    %Operation{
-      tags: ["Accounts"],
-      summary: "Resend confirmation email. Expects `email` or `nickname`",
+      tags: ["Account credentials"],
+      summary: "Resend confirmation email",
+      description: "Expects `email` or `nickname`.",
      operationId: "PleromaAPI.AccountController.confirmation_resend",
      parameters: [
        Operation.parameter(:email, :query, :string, "Email of that needs to be verified",
@ -41,8 +42,10 @@ defmodule Pleroma.Web.ApiSpec.PleromaAccountOperation do

  def favourites_operation do
    %Operation{
-      tags: ["Accounts"],
-      summary: "Returns favorites timeline of any user",
+      tags: ["Retrieve account information"],
+      summary: "Favorites",
+      description:
+        "Only returns data if the user has opted into sharing it. See `hide_favorites` in [Update account credentials](#operation/AccountController.update_credentials).",
      operationId: "PleromaAPI.AccountController.favourites",
      parameters: [id_param() | pagination_params()],
      security: [%{"oAuth" => ["read:favourites"]}],
@ -61,8 +64,9 @@ defmodule Pleroma.Web.ApiSpec.PleromaAccountOperation do

  def subscribe_operation do
    %Operation{
-      tags: ["Accounts"],
-      summary: "Subscribe to receive notifications for all statuses posted by a user",
+      tags: ["Account actions"],
+      summary: "Subscribe",
+      description: "Receive notifications for all statuses posted by the account.",
      operationId: "PleromaAPI.AccountController.subscribe",
      parameters: [id_param()],
      security: [%{"oAuth" => ["follow", "write:follows"]}],
@ -75,8 +79,9 @@ defmodule Pleroma.Web.ApiSpec.PleromaAccountOperation do

  def unsubscribe_operation do
    %Operation{
-      tags: ["Accounts"],
-      summary: "Unsubscribe to stop receiving notifications from user statuses",
+      tags: ["Account actions"],
+      summary: "Unsubscribe",
+      description: "Stop receiving notifications for all statuses posted by the account.",
      operationId: "PleromaAPI.AccountController.unsubscribe",
      parameters: [id_param()],
      security: [%{"oAuth" => ["follow", "write:follows"]}],
--- a/lib/pleroma/web/api_spec/operations/pleroma_conversation_operation.ex
+++ b/lib/pleroma/web/api_spec/operations/pleroma_conversation_operation.ex
@ -19,7 +19,7 @@ defmodule Pleroma.Web.ApiSpec.PleromaConversationOperation do
  def show_operation do
    %Operation{
      tags: ["Conversations"],
-      summary: "The conversation with the given ID",
+      summary: "Conversation",
      parameters: [
        Operation.parameter(:id, :path, :string, "Conversation ID",
          example: "123",
@ -37,7 +37,7 @@ defmodule Pleroma.Web.ApiSpec.PleromaConversationOperation do
  def statuses_operation do
    %Operation{
      tags: ["Conversations"],
-      summary: "Timeline for a given conversation",
+      summary: "Timeline for conversation",
      parameters: [
        Operation.parameter(:id, :path, :string, "Conversation ID",
          example: "123",
@ -61,7 +61,8 @@ defmodule Pleroma.Web.ApiSpec.PleromaConversationOperation do
  def update_operation do
    %Operation{
      tags: ["Conversations"],
-      summary: "Update a conversation. Used to change the set of recipients.",
+      summary: "Update conversation",
+      description: "Change set of recipients for the conversation.",
      parameters: [
        Operation.parameter(:id, :path, :string, "Conversation ID",
          example: "123",
@ -86,7 +87,7 @@ defmodule Pleroma.Web.ApiSpec.PleromaConversationOperation do
  def mark_as_read_operation do
    %Operation{
      tags: ["Conversations"],
-      summary: "Marks all user's conversations as read",
+      summary: "Marks all conversations as read",
      security: [%{"oAuth" => ["write:conversations"]}],
      operationId: "PleromaAPI.ConversationController.mark_as_read",
      responses: %{
--- a/lib/pleroma/web/api_spec/operations/pleroma_emoji_file_operation.ex
+++ b/lib/pleroma/web/api_spec/operations/pleroma_emoji_file_operation.ex
@ -16,7 +16,7 @@ defmodule Pleroma.Web.ApiSpec.PleromaEmojiFileOperation do

  def create_operation do
    %Operation{
-      tags: ["Emoji Packs"],
+      tags: ["Emoji packs"],
      summary: "Add new file to the pack",
      operationId: "PleromaAPI.EmojiPackController.add_file",
      security: [%{"oAuth" => ["write"]}],
@ -62,7 +62,7 @@ defmodule Pleroma.Web.ApiSpec.PleromaEmojiFileOperation do

  def update_operation do
    %Operation{
-      tags: ["Emoji Packs"],
+      tags: ["Emoji packs"],
      summary: "Add new file to the pack",
      operationId: "PleromaAPI.EmojiPackController.update_file",
      security: [%{"oAuth" => ["write"]}],
@ -106,7 +106,7 @@ defmodule Pleroma.Web.ApiSpec.PleromaEmojiFileOperation do

  def delete_operation do
    %Operation{
-      tags: ["Emoji Packs"],
+      tags: ["Emoji packs"],
      summary: "Delete emoji file from pack",
      operationId: "PleromaAPI.EmojiPackController.delete_file",
      security: [%{"oAuth" => ["write"]}],
--- a/lib/pleroma/web/api_spec/operations/pleroma_emoji_pack_operation.ex
+++ b/lib/pleroma/web/api_spec/operations/pleroma_emoji_pack_operation.ex
@ -16,7 +16,7 @@ defmodule Pleroma.Web.ApiSpec.PleromaEmojiPackOperation do

  def remote_operation do
    %Operation{
-      tags: ["Emoji Packs"],
+      tags: ["Emoji packs"],
      summary: "Make request to another instance for emoji packs list",
      security: [%{"oAuth" => ["write"]}],
      parameters: [
@ -44,7 +44,7 @@ defmodule Pleroma.Web.ApiSpec.PleromaEmojiPackOperation do

  def index_operation do
    %Operation{
-      tags: ["Emoji Packs"],
+      tags: ["Emoji packs"],
      summary: "Lists local custom emoji packs",
      operationId: "PleromaAPI.EmojiPackController.index",
      parameters: [
@ -69,7 +69,7 @@ defmodule Pleroma.Web.ApiSpec.PleromaEmojiPackOperation do

  def show_operation do
    %Operation{
-      tags: ["Emoji Packs"],
+      tags: ["Emoji packs"],
      summary: "Show emoji pack",
      operationId: "PleromaAPI.EmojiPackController.show",
      parameters: [
@ -97,7 +97,7 @@ defmodule Pleroma.Web.ApiSpec.PleromaEmojiPackOperation do

  def archive_operation do
    %Operation{
-      tags: ["Emoji Packs"],
+      tags: ["Emoji packs"],
      summary: "Requests a local pack archive from the instance",
      operationId: "PleromaAPI.EmojiPackController.archive",
      parameters: [name_param()],
@ -115,7 +115,7 @@ defmodule Pleroma.Web.ApiSpec.PleromaEmojiPackOperation do

  def download_operation do
    %Operation{
-      tags: ["Emoji Packs"],
+      tags: ["Emoji packs"],
      summary: "Download pack from another instance",
      operationId: "PleromaAPI.EmojiPackController.download",
      security: [%{"oAuth" => ["write"]}],
@ -145,7 +145,7 @@ defmodule Pleroma.Web.ApiSpec.PleromaEmojiPackOperation do

  def create_operation do
    %Operation{
-      tags: ["Emoji Packs"],
+      tags: ["Emoji packs"],
      summary: "Create an empty pack",
      operationId: "PleromaAPI.EmojiPackController.create",
      security: [%{"oAuth" => ["write"]}],
@ -161,7 +161,7 @@ defmodule Pleroma.Web.ApiSpec.PleromaEmojiPackOperation do

  def delete_operation do
    %Operation{
-      tags: ["Emoji Packs"],
+      tags: ["Emoji packs"],
      summary: "Delete a custom emoji pack",
      operationId: "PleromaAPI.EmojiPackController.delete",
      security: [%{"oAuth" => ["write"]}],
@ -177,7 +177,7 @@ defmodule Pleroma.Web.ApiSpec.PleromaEmojiPackOperation do

  def update_operation do
    %Operation{
-      tags: ["Emoji Packs"],
+      tags: ["Emoji packs"],
      summary: "Updates (replaces) pack metadata",
      operationId: "PleromaAPI.EmojiPackController.update",
      security: [%{"oAuth" => ["write"]}],
@ -193,7 +193,7 @@ defmodule Pleroma.Web.ApiSpec.PleromaEmojiPackOperation do

  def import_from_filesystem_operation do
    %Operation{
-      tags: ["Emoji Packs"],
+      tags: ["Emoji packs"],
      summary: "Imports packs from filesystem",
      operationId: "PleromaAPI.EmojiPackController.import",
      security: [%{"oAuth" => ["write"]}],
--- a/lib/pleroma/web/api_spec/operations/pleroma_instances_operation.ex
+++ b/lib/pleroma/web/api_spec/operations/pleroma_instances_operation.ex
@ -13,8 +13,8 @@ defmodule Pleroma.Web.ApiSpec.PleromaInstancesOperation do

  def show_operation do
    %Operation{
-      tags: ["PleromaInstances"],
-      summary: "Instances federation status",
+      tags: ["Instance"],
+      summary: "Retrieve federation status",
      description: "Information about instances deemed unreachable by the server",
      operationId: "PleromaInstances.show",
      responses: %{
--- a/lib/pleroma/web/api_spec/operations/pleroma_mascot_operation.ex
+++ b/lib/pleroma/web/api_spec/operations/pleroma_mascot_operation.ex
@ -17,7 +17,7 @@ defmodule Pleroma.Web.ApiSpec.PleromaMascotOperation do
  def show_operation do
    %Operation{
      tags: ["Mascot"],
-      summary: "Gets user mascot image",
+      summary: "Retrieve mascot",
      security: [%{"oAuth" => ["read:accounts"]}],
      operationId: "PleromaAPI.MascotController.show",
      responses: %{
@ -29,7 +29,7 @@ defmodule Pleroma.Web.ApiSpec.PleromaMascotOperation do
  def update_operation do
    %Operation{
      tags: ["Mascot"],
-      summary: "Set/clear user avatar image",
+      summary: "Set or clear mascot",
      description:
        "Behaves exactly the same as `POST /api/v1/upload`. Can only accept images - any attempt to upload non-image files will be met with `HTTP 415 Unsupported Media Type`.",
      operationId: "PleromaAPI.MascotController.update",
--- a/lib/pleroma/web/api_spec/operations/pleroma_notification_operation.ex
+++ b/lib/pleroma/web/api_spec/operations/pleroma_notification_operation.ex
@ -18,7 +18,8 @@ defmodule Pleroma.Web.ApiSpec.PleromaNotificationOperation do
  def mark_as_read_operation do
    %Operation{
      tags: ["Notifications"],
-      summary: "Mark notifications as read. Query parameters are mutually exclusive.",
+      summary: "Mark notifications as read",
+      description: "Query parameters are mutually exclusive.",
      requestBody:
        request_body("Parameters", %Schema{
          type: :object,
@ -32,7 +33,7 @@ defmodule Pleroma.Web.ApiSpec.PleromaNotificationOperation do
      responses: %{
        200 =>
          Operation.response(
-            "A Notification or array of Motifications",
+            "A Notification or array of Notifications",
            "application/json",
            %Schema{
              anyOf: [
--- a/lib/pleroma/web/api_spec/operations/report_operation.ex
+++ b/lib/pleroma/web/api_spec/operations/report_operation.ex
@ -16,7 +16,7 @@ defmodule Pleroma.Web.ApiSpec.ReportOperation do

  def create_operation do
    %Operation{
-      tags: ["reports"],
+      tags: ["Reports"],
      summary: "File a report",
      description: "Report problematic users to your moderators",
      operationId: "ReportController.create",
--- a/lib/pleroma/web/api_spec/operations/scheduled_activity_operation.ex
+++ b/lib/pleroma/web/api_spec/operations/scheduled_activity_operation.ex
@ -18,7 +18,7 @@ defmodule Pleroma.Web.ApiSpec.ScheduledActivityOperation do

  def index_operation do
    %Operation{
-      tags: ["Scheduled Statuses"],
+      tags: ["Scheduled statuses"],
      summary: "View scheduled statuses",
      security: [%{"oAuth" => ["read:statuses"]}],
      parameters: pagination_params(),
@ -35,7 +35,7 @@ defmodule Pleroma.Web.ApiSpec.ScheduledActivityOperation do

  def show_operation do
    %Operation{
-      tags: ["Scheduled Statuses"],
+      tags: ["Scheduled statuses"],
      summary: "View a single scheduled status",
      security: [%{"oAuth" => ["read:statuses"]}],
      parameters: [id_param()],
@ -49,7 +49,7 @@ defmodule Pleroma.Web.ApiSpec.ScheduledActivityOperation do

  def update_operation do
    %Operation{
-      tags: ["Scheduled Statuses"],
+      tags: ["Scheduled statuses"],
      summary: "Schedule a status",
      operationId: "ScheduledActivity.update",
      security: [%{"oAuth" => ["write:statuses"]}],
@ -75,7 +75,7 @@ defmodule Pleroma.Web.ApiSpec.ScheduledActivityOperation do

  def delete_operation do
    %Operation{
-      tags: ["Scheduled Statuses"],
+      tags: ["Scheduled statuses"],
      summary: "Cancel a scheduled status",
      security: [%{"oAuth" => ["write:statuses"]}],
      parameters: [id_param()],
--- a/lib/pleroma/web/api_spec/operations/status_operation.ex
+++ b/lib/pleroma/web/api_spec/operations/status_operation.ex
@ -22,8 +22,8 @@ defmodule Pleroma.Web.ApiSpec.StatusOperation do

  def index_operation do
    %Operation{
-      tags: ["Statuses"],
-      summary: "Get multiple statuses by IDs",
+      tags: ["Retrieve status information"],
+      summary: "Multiple statuses",
      security: [%{"oAuth" => ["read:statuses"]}],
      parameters: [
        Operation.parameter(
@ -48,7 +48,7 @@ defmodule Pleroma.Web.ApiSpec.StatusOperation do

  def create_operation do
    %Operation{
-      tags: ["Statuses"],
+      tags: ["Status actions"],
      summary: "Publish new status",
      security: [%{"oAuth" => ["write:statuses"]}],
      description: "Post a new status",
@ -68,8 +68,8 @@ defmodule Pleroma.Web.ApiSpec.StatusOperation do

  def show_operation do
    %Operation{
-      tags: ["Statuses"],
-      summary: "View specific status",
+      tags: ["Retrieve status information"],
+      summary: "Status",
      description: "View information about a status",
      operationId: "StatusController.show",
      security: [%{"oAuth" => ["read:statuses"]}],
@ -91,8 +91,8 @@ defmodule Pleroma.Web.ApiSpec.StatusOperation do

  def delete_operation do
    %Operation{
-      tags: ["Statuses"],
-      summary: "Delete status",
+      tags: ["Status actions"],
+      summary: "Delete",
      security: [%{"oAuth" => ["write:statuses"]}],
      description: "Delete one of your own statuses",
      operationId: "StatusController.delete",
@ -107,8 +107,8 @@ defmodule Pleroma.Web.ApiSpec.StatusOperation do

  def reblog_operation do
    %Operation{
-      tags: ["Statuses"],
-      summary: "Boost",
+      tags: ["Status actions"],
+      summary: "Reblog",
      security: [%{"oAuth" => ["write:statuses"]}],
      description: "Share a status",
      operationId: "StatusController.reblog",
@ -129,8 +129,8 @@ defmodule Pleroma.Web.ApiSpec.StatusOperation do

  def unreblog_operation do
    %Operation{
-      tags: ["Statuses"],
-      summary: "Undo boost",
+      tags: ["Status actions"],
+      summary: "Undo reblog",
      security: [%{"oAuth" => ["write:statuses"]}],
      description: "Undo a reshare of a status",
      operationId: "StatusController.unreblog",
@ -144,7 +144,7 @@ defmodule Pleroma.Web.ApiSpec.StatusOperation do

  def favourite_operation do
    %Operation{
-      tags: ["Statuses"],
+      tags: ["Status actions"],
      summary: "Favourite",
      security: [%{"oAuth" => ["write:favourites"]}],
      description: "Add a status to your favourites list",
@ -159,7 +159,7 @@ defmodule Pleroma.Web.ApiSpec.StatusOperation do

  def unfavourite_operation do
    %Operation{
-      tags: ["Statuses"],
+      tags: ["Status actions"],
      summary: "Undo favourite",
      security: [%{"oAuth" => ["write:favourites"]}],
      description: "Remove a status from your favourites list",
@ -174,7 +174,7 @@ defmodule Pleroma.Web.ApiSpec.StatusOperation do

  def pin_operation do
    %Operation{
-      tags: ["Statuses"],
+      tags: ["Status actions"],
      summary: "Pin to profile",
      security: [%{"oAuth" => ["write:accounts"]}],
      description: "Feature one of your own public statuses at the top of your profile",
@ -189,8 +189,8 @@ defmodule Pleroma.Web.ApiSpec.StatusOperation do

  def unpin_operation do
    %Operation{
-      tags: ["Statuses"],
-      summary: "Unpin to profile",
+      tags: ["Status actions"],
+      summary: "Unpin from profile",
      security: [%{"oAuth" => ["write:accounts"]}],
      description: "Unfeature a status from the top of your profile",
      operationId: "StatusController.unpin",
@ -204,7 +204,7 @@ defmodule Pleroma.Web.ApiSpec.StatusOperation do

  def bookmark_operation do
    %Operation{
-      tags: ["Statuses"],
+      tags: ["Status actions"],
      summary: "Bookmark",
      security: [%{"oAuth" => ["write:bookmarks"]}],
      description: "Privately bookmark a status",
@ -218,7 +218,7 @@ defmodule Pleroma.Web.ApiSpec.StatusOperation do

  def unbookmark_operation do
    %Operation{
-      tags: ["Statuses"],
+      tags: ["Status actions"],
      summary: "Undo bookmark",
      security: [%{"oAuth" => ["write:bookmarks"]}],
      description: "Remove a status from your private bookmarks",
@ -232,7 +232,7 @@ defmodule Pleroma.Web.ApiSpec.StatusOperation do

  def mute_conversation_operation do
    %Operation{
-      tags: ["Statuses"],
+      tags: ["Status actions"],
      summary: "Mute conversation",
      security: [%{"oAuth" => ["write:mutes"]}],
      description: "Do not receive notifications for the thread that this status is part of.",
@ -267,7 +267,7 @@ defmodule Pleroma.Web.ApiSpec.StatusOperation do

  def unmute_conversation_operation do
    %Operation{
-      tags: ["Statuses"],
+      tags: ["Status actions"],
      summary: "Unmute conversation",
      security: [%{"oAuth" => ["write:mutes"]}],
      description:
@ -283,7 +283,7 @@ defmodule Pleroma.Web.ApiSpec.StatusOperation do

  def card_operation do
    %Operation{
-      tags: ["Statuses"],
+      tags: ["Retrieve status information"],
      deprecated: true,
      summary: "Preview card",
      description: "Deprecated in favor of card property inlined on Status entity",
@ -311,7 +311,7 @@ defmodule Pleroma.Web.ApiSpec.StatusOperation do

  def favourited_by_operation do
    %Operation{
-      tags: ["Statuses"],
+      tags: ["Retrieve status information"],
      summary: "Favourited by",
      description: "View who favourited a given status",
      operationId: "StatusController.favourited_by",
@ -331,9 +331,9 @@ defmodule Pleroma.Web.ApiSpec.StatusOperation do

  def reblogged_by_operation do
    %Operation{
-      tags: ["Statuses"],
-      summary: "Boosted by",
-      description: "View who boosted a given status",
+      tags: ["Retrieve status information"],
+      summary: "Reblogged by",
+      description: "View who reblogged a given status",
      operationId: "StatusController.reblogged_by",
      security: [%{"oAuth" => ["read:accounts"]}],
      parameters: [id_param()],
@ -351,7 +351,7 @@ defmodule Pleroma.Web.ApiSpec.StatusOperation do

  def context_operation do
    %Operation{
-      tags: ["Statuses"],
+      tags: ["Retrieve status information"],
      summary: "Parent and child statuses",
      description: "View statuses above and below this status in the thread",
      operationId: "StatusController.context",
@ -365,7 +365,7 @@ defmodule Pleroma.Web.ApiSpec.StatusOperation do

  def favourites_operation do
    %Operation{
-      tags: ["Statuses"],
+      tags: ["Timelines"],
      summary: "Favourited statuses",
      description:
        "Statuses the user has favourited. Please note that you have to use the link headers to paginate this. You can not build the query parameters yourself.",
@ -380,7 +380,7 @@ defmodule Pleroma.Web.ApiSpec.StatusOperation do

  def bookmarks_operation do
    %Operation{
-      tags: ["Statuses"],
+      tags: ["Timelines"],
      summary: "Bookmarked statuses",
      description: "Statuses the user has bookmarked",
      operationId: "StatusController.bookmarks",
--- a/lib/pleroma/web/api_spec/operations/subscription_operation.ex
+++ b/lib/pleroma/web/api_spec/operations/subscription_operation.ex
@ -17,7 +17,7 @@ defmodule Pleroma.Web.ApiSpec.SubscriptionOperation do

  def create_operation do
    %Operation{
-      tags: ["Push Subscriptions"],
+      tags: ["Push subscriptions"],
      summary: "Subscribe to push notifications",
      description:
        "Add a Web Push API subscription to receive notifications. Each access token can have one push subscription. If you create a new subscription, the old subscription is deleted.",
@ -25,7 +25,7 @@ defmodule Pleroma.Web.ApiSpec.SubscriptionOperation do
      security: [%{"oAuth" => ["push"]}],
      requestBody: Helpers.request_body("Parameters", create_request(), required: true),
      responses: %{
-        200 => Operation.response("Push Subscription", "application/json", PushSubscription),
+        200 => Operation.response("Push subscription", "application/json", PushSubscription),
        400 => Operation.response("Error", "application/json", ApiError),
        403 => Operation.response("Error", "application/json", ApiError)
      }
@ -34,13 +34,13 @@ defmodule Pleroma.Web.ApiSpec.SubscriptionOperation do

  def show_operation do
    %Operation{
-      tags: ["Push Subscriptions"],
+      tags: ["Push subscriptions"],
      summary: "Get current subscription",
      description: "View the PushSubscription currently associated with this access token.",
      operationId: "SubscriptionController.show",
      security: [%{"oAuth" => ["push"]}],
      responses: %{
-        200 => Operation.response("Push Subscription", "application/json", PushSubscription),
+        200 => Operation.response("Push subscription", "application/json", PushSubscription),
        403 => Operation.response("Error", "application/json", ApiError),
        404 => Operation.response("Error", "application/json", ApiError)
      }
@ -49,7 +49,7 @@ defmodule Pleroma.Web.ApiSpec.SubscriptionOperation do

  def update_operation do
    %Operation{
-      tags: ["Push Subscriptions"],
+      tags: ["Push subscriptions"],
      summary: "Change types of notifications",
      description:
        "Updates the current push subscription. Only the data part can be updated. To change fundamentals, a new subscription must be created instead.",
@ -57,7 +57,7 @@ defmodule Pleroma.Web.ApiSpec.SubscriptionOperation do
      security: [%{"oAuth" => ["push"]}],
      requestBody: Helpers.request_body("Parameters", update_request(), required: true),
      responses: %{
-        200 => Operation.response("Push Subscription", "application/json", PushSubscription),
+        200 => Operation.response("Push subscription", "application/json", PushSubscription),
        403 => Operation.response("Error", "application/json", ApiError)
      }
    }
@ -65,7 +65,7 @@ defmodule Pleroma.Web.ApiSpec.SubscriptionOperation do

  def delete_operation do
    %Operation{
-      tags: ["Push Subscriptions"],
+      tags: ["Push subscriptions"],
      summary: "Remove current subscription",
      description: "Removes the current Web Push API subscription.",
      operationId: "SubscriptionController.delete",
--- a/lib/pleroma/web/api_spec/operations/timeline_operation.ex
+++ b/lib/pleroma/web/api_spec/operations/timeline_operation.ex
@ -41,8 +41,7 @@ defmodule Pleroma.Web.ApiSpec.TimelineOperation do
      tags: ["Timelines"],
      summary: "Direct timeline",
      description:
-        "View statuses with a “direct” privacy, from your account or in your notifications",
-      deprecated: true,
+        "View statuses with a “direct” scope addressed to the account. Using this endpoint is discouraged, please use [conversations](#tag/Conversations) or [chats](#tag/Chats).",
      parameters: [with_muted_param() | pagination_params()],
      security: [%{"oAuth" => ["read:statuses"]}],
      operationId: "TimelineController.direct",
--- a/lib/pleroma/web/api_spec/operations/user_import_operation.ex
+++ b/lib/pleroma/web/api_spec/operations/user_import_operation.ex
@ -17,8 +17,8 @@ defmodule Pleroma.Web.ApiSpec.UserImportOperation do

  def follow_operation do
    %Operation{
-      tags: ["follow_import"],
-      summary: "Imports your follows.",
+      tags: ["Data import"],
+      summary: "Import follows",
      operationId: "UserImportController.follow",
      requestBody: request_body("Parameters", import_request(), required: true),
      responses: %{
@ -31,8 +31,8 @@ defmodule Pleroma.Web.ApiSpec.UserImportOperation do

  def blocks_operation do
    %Operation{
-      tags: ["blocks_import"],
-      summary: "Imports your blocks.",
+      tags: ["Data import"],
+      summary: "Import blocks",
      operationId: "UserImportController.blocks",
      requestBody: request_body("Parameters", import_request(), required: true),
      responses: %{
@ -45,8 +45,8 @@ defmodule Pleroma.Web.ApiSpec.UserImportOperation do

  def mutes_operation do
    %Operation{
-      tags: ["mutes_import"],
-      summary: "Imports your mutes.",
+      tags: ["Data import"],
+      summary: "Import mutes",
      operationId: "UserImportController.mutes",
      requestBody: request_body("Parameters", import_request(), required: true),
      responses: %{