1 files changed, 84 insertions, 9 deletions

diff --git a/lib/pleroma/web/api_spec.ex b/lib/pleroma/web/api_spec.ex
index 064558597..adc8762dc 100644
--- 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,26 @@ 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!
+        """,
+        # Strip environment from the version
+        version: Application.spec(:pleroma, :vsn) |> to_string() |> String.replace(~r/\+.*$/, ""),
+        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 +62,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 pack administration",
+              "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" => ["Emoji packs", "Reports", "Suggestions"]}
+        ]
       }
     }
     # discover request/response schemas from path specs