Add swaggerUI options (#66)

Reviewed-on: https://akkoma.dev/AkkomaGang/akkoma/pulls/66

config/config.exs

@@ -719,6 +719,11 @@
 
 config :pleroma, :frontends,
   primary: %{"name" => "pleroma-fe", "ref" => "develop"},
+  swagger: %{
+    "name" => "swagger-ui",
+    "ref" => "stable",
+    "enabled" => false
+  },
   available: %{
     "pleroma-fe" => %{
       "name" => "pleroma-fe",
@@ -748,6 +753,14 @@
         "https://gitlab.com/soapbox-pub/soapbox-fe/-/jobs/artifacts/${ref}/download?job=build-production",
       "ref" => "v1.0.0",
       "build_dir" => "static"
+    },
+    # For developers - enables a swagger frontend to view the openapi spec
+    "swagger-ui" => %{
+      "name" => "swagger-ui",
+      "git" => "https://github.com/swagger-api/swagger-ui",
+      "build_url" => "https://akkoma-updates.s3-website.fr-par.scw.cloud/frontend/swagger-ui.zip",
+      "build_dir" => "dist",
+      "ref" => "stable"
     }
   }
 

config/description.exs

@@ -3089,6 +3089,21 @@
         description: "Admin frontend",
         children: installed_frontend_options
       },
+      %{
+        key: :swagger,
+        type: :map,
+        description: "Swagger API reference frontend",
+        children:
+          installed_frontend_options ++
+            [
+              %{
+                key: "enabled",
+                label: "Enabled",
+                type: :boolean,
+                description: "Whether to have this enabled at all"
+              }
+            ]
+      },
       %{
         key: :available,
         type: :map,

docs/configuration/cheatsheet.md

@@ -270,6 +270,33 @@ config :pleroma, :frontend_configurations,
 
 These settings **need to be complete**, they will override the defaults.
 
+### :frontends
+
+These settings tell akkoma which frontend files to serve the user.
+
+See: [Frontend Management](../frontend_management)
+
+```elixir
+config :pleroma, :frontends,
+  primary: %{
+    "name" => "pleroma-fe",
+    "ref" => "develop"
+  },
+  admin: %{
+    "name" => "admin-fe",
+    "ref" => "develop"
+  },
+  swagger: %{
+    "name" => "swagger-ui",
+    "ref" => "stable",
+    "enabled" => true
+  } 
+```
+
+* `:primary` - The frontend that will be served at `/`
+* `:admin` - The frontend that will be served at `/pleroma/admin`
+* `:swagger` - Config for developers to act as an API reference to be served at `/akkoma/swaggerui/` (trailing slash _needed_). Disabled by default.
+
 ### :static_fe
 
 Render profiles and posts using server-generated HTML that is viewable without using JavaScript.
@@ -1088,40 +1115,6 @@ Control favicons for instances.
     4. C:\TMP on Windows or /tmp on Unix-like operating systems
     5. as a last resort, the current working directory
 
-## Frontend management
-
-Frontends in Akkoma are swappable - you can specify which one to use here.
-
-You can set a frontends for the key `primary` and `admin` and the options of `name` and `ref`. This will then make Akkoma serve the frontend from a folder constructed by concatenating the instance static path, `frontends` and the name and ref.
-
-The key `primary` refers to the frontend that will be served by default for general requests. The key `admin` refers to the frontend that will be served at the `/pleroma/admin` path.
-
-If you don't set anything here, you will not have _any_ frontend at all.
-
-Example:
-
-```
-config :pleroma, :frontends,
-  primary: %{
-    "name" => "pleroma",
-    "ref" => "stable"
-  },
-  admin: %{
-    "name" => "admin",
-    "ref" => "develop"
-  }
-```
-
-This would serve the frontend from the the folder at `$instance_static/frontends/pleroma/stable`. You have to copy the frontend into this folder yourself. You can choose the name and ref any way you like, but they will be used by mix tasks to automate installation in the future, the name referring to the project and the ref referring to a commit.
-
-Refer to [the frontend CLI task](../../administration/CLI_tasks/frontend) for how to install the frontend's files
-
-If you wish masto-fe to also be enabled, you will also need to run the install task for `mastodon-fe`. Not doing this will lead to the frontend not working.
-
-If you choose not to install a frontend for whatever reason, it is recommended that you enable [`:static_fe`](#static_fe) to allow remote users to click "view remote source". Don't bother with this if you've got no unauthenticated access though.
-
-You can also replace the default "no frontend" page by placing an `index.html` file under your `instance/static/` directory.
-
 ### Theme settings
 
 Settings to change theme as exposed to the outside world, for software

docs/configuration/frontend_management.md

@@ -0,0 +1,60 @@
+# Frontend Management
+
+Frontends in Akkoma are swappable, you can pick which you'd like.
+
+For a basic setup, you can set a frontends for the key `primary` and `admin` and the options of `name` and `ref`. This will then make Akkoma serve the frontend from a folder constructed by concatenating the instance static path, `frontends` and the name and ref.
+
+The key `primary` refers to the frontend that will be served by default for general requests. The key `admin` refers to the frontend that will be served at the `/pleroma/admin` path.
+
+If you don't set anything here, you will not have _any_ frontend at all.
+
+Example:
+
+```elixir
+config :pleroma, :frontends,
+  primary: %{
+    "name" => "pleroma",
+    "ref" => "stable"
+  },
+  admin: %{
+    "name" => "admin",
+    "ref" => "develop"
+  },
+  dwarves: %{
+    "name" => "diggydiggy",
+    "ref" => "hole"
+  },
+  extra: [
+    %{"subdomain" => "dwarves", "key" => :dwarves}
+  ]
+```
+
+This would serve the frontend from the the folder at `$instance_static/frontends/pleroma/stable`. You have to copy the frontend into this folder yourself. You can choose the name and ref any way you like, but they will be used by mix tasks to automate installation in the future, the name referring to the project and the ref referring to a commit.
+
+Refer to [the frontend CLI task](../../administration/CLI_tasks/frontend) for how to install the frontend's files
+
+If you wish masto-fe to also be enabled, you will also need to run the install task for `mastodon-fe`. Not doing this will lead to the frontend not working.
+
+If you choose not to install a frontend for whatever reason, it is recommended that you enable [`:static_fe`](#static_fe) to allow remote users to click "view remote source". Don't bother with this if you've got no unauthenticated access though.
+
+You can also replace the default "no frontend" page by placing an `index.html` file under your `instance/static/` directory.
+
+## Swagger (openAPI) documentation viewer
+
+If you're a developer and you'd like a human-readable rendering of the
+API documentation, you can enable [Swagger UI](https://github.com/swagger-api/swagger-ui).
+
+In your config:
+
+```elixir
+config :pleroma, :frontends,
+  swagger: %{
+    "name" => "swagger-ui",
+    "ref" => "stable",
+    "enabled" => true
+  }
+```
+
+Then run the [pleroma.frontend cli task](../../administration/CLI_tasks/frontend) with the name of `swagger-ui` to install the distribution files.
+
+You will now be able to view documentation at `/akkoma/swaggerui`

lib/akkoma/web/swagger.ex

@@ -0,0 +1,7 @@
+defmodule Akkoma.Web.Swagger do
+  alias Pleroma.Config
+
+  def ui_enabled? do
+    Config.get([:frontends, :swagger, "enabled"])
+  end
+end

lib/pleroma/application.ex

@@ -82,7 +82,17 @@ def start(_type, _args) do
 
     # See http://elixir-lang.org/docs/stable/elixir/Supervisor.html
     # for other strategies and supported options
-    opts = [strategy: :one_for_one, name: Pleroma.Supervisor]
+    # If we have a lot of caches, default max_restarts can cause test
+    # resets to fail.
+    # Go for the default 3 unless we're in test
+    max_restarts =
+      if @mix_env == :test do
+        100
+      else
+        3
+      end
+
+    opts = [strategy: :one_for_one, name: Pleroma.Supervisor, max_restarts: max_restarts]
     result = Supervisor.start_link(children, opts)
 
     set_postgres_server_version()

lib/pleroma/web/endpoint.ex

@@ -66,12 +66,13 @@ defmodule Pleroma.Web.Endpoint do
     }
   )
 
-  plug(Plug.Static.IndexHtml, at: "/pleroma/fedife/")
+  plug(Plug.Static.IndexHtml, at: "/akkoma/swaggerui")
 
   plug(Pleroma.Web.Plugs.FrontendStatic,
-    at: "/pleroma/fedife",
+    at: "/akkoma/swaggerui",
-    frontend_type: :fedife,
+    frontend_type: :swagger,
     gzip: true,
+    if: &Akkoma.Web.Swagger.ui_enabled?/0,
     cache_control_for_etags: @static_cache_control,
     headers: %{
       "cache-control" => @static_cache_control

lib/pleroma/web/plugs/frontend_static.ex

@@ -31,11 +31,13 @@ def init(opts) do
     |> Keyword.put(:from, "__unconfigured_frontend_static_plug")
     |> Plug.Static.init()
     |> Map.put(:frontend_type, opts[:frontend_type])
+    |> Map.put(:if, Keyword.get(opts, :if, fn -> true end))
   end
 
   def call(conn, opts) do
     with false <- api_route?(conn.path_info),
          false <- invalid_path?(conn.path_info),
+         true <- opts[:if].(),
          frontend_type <- Map.get(opts, :frontend_type, :primary),
          path when not is_nil(path) <- file_path("", frontend_type) do
       call_static(conn, opts, path)

mix.exs

@@ -133,7 +133,7 @@ defp deps do
       {:html_entities, "~> 0.5", override: true},
       {:phoenix_html, "~> 3.1", override: true},
       {:calendar, "~> 1.0"},
-      {:cachex, "~> 3.2"},
+      {:cachex, "~> 3.4"},
       {:poison, "~> 3.0", override: true},
       {:tesla, "~> 1.4.4", override: true},
       {:castore, "~> 0.1"},

mix.lock

@@ -7,7 +7,7 @@
   "bcrypt_elixir": {:hex, :bcrypt_elixir, "2.3.0", "6cb662d5c1b0a8858801cf20997bd006e7016aa8c52959c9ef80e0f34fb60b7a", [:make, :mix], [{:comeonin, "~> 5.3", [hex: :comeonin, repo: "hexpm", optional: false]}, {:elixir_make, "~> 0.6", [hex: :elixir_make, repo: "hexpm", optional: false]}], "hexpm", "2c81d61d4f6ed0e5cf7bf27a9109b791ff216a1034b3d541327484f46dd43769"},
   "benchee": {:hex, :benchee, "1.0.1", "66b211f9bfd84bd97e6d1beaddf8fc2312aaabe192f776e8931cb0c16f53a521", [:mix], [{:deep_merge, "~> 1.0", [hex: :deep_merge, repo: "hexpm", optional: false]}], "hexpm", "3ad58ae787e9c7c94dd7ceda3b587ec2c64604563e049b2a0e8baafae832addb"},
   "bunt": {:hex, :bunt, "0.2.0", "951c6e801e8b1d2cbe58ebbd3e616a869061ddadcc4863d0a2182541acae9a38", [:mix], [], "hexpm", "7af5c7e09fe1d40f76c8e4f9dd2be7cebd83909f31fee7cd0e9eadc567da8353"},
-  "cachex": {:hex, :cachex, "3.3.0", "6f2ebb8f27491fe39121bd207c78badc499214d76c695658b19d6079beeca5c2", [:mix], [{:eternal, "~> 1.2", [hex: :eternal, repo: "hexpm", optional: false]}, {:jumper, "~> 1.0", [hex: :jumper, repo: "hexpm", optional: false]}, {:sleeplocks, "~> 1.1", [hex: :sleeplocks, repo: "hexpm", optional: false]}, {:unsafe, "~> 1.0", [hex: :unsafe, repo: "hexpm", optional: false]}], "hexpm", "d90e5ee1dde14cef33f6b187af4335b88748b72b30c038969176cd4e6ccc31a1"},
+  "cachex": {:hex, :cachex, "3.4.0", "868b2959ea4aeb328c6b60ff66c8d5123c083466ad3c33d3d8b5f142e13101fb", [:mix], [{:eternal, "~> 1.2", [hex: :eternal, repo: "hexpm", optional: false]}, {:jumper, "~> 1.0", [hex: :jumper, repo: "hexpm", optional: false]}, {:sleeplocks, "~> 1.1", [hex: :sleeplocks, repo: "hexpm", optional: false]}, {:unsafe, "~> 1.0", [hex: :unsafe, repo: "hexpm", optional: false]}], "hexpm", "370123b1ab4fba4d2965fb18f87fd758325709787c8c5fce35b3fe80645ccbe5"},
   "calendar": {:hex, :calendar, "1.0.0", "f52073a708528482ec33d0a171954ca610fe2bd28f1e871f247dc7f1565fa807", [:mix], [{:tzdata, "~> 0.5.20 or ~> 0.1.201603 or ~> 1.0", [hex: :tzdata, repo: "hexpm", optional: false]}], "hexpm", "990e9581920c82912a5ee50e62ff5ef96da6b15949a2ee4734f935fdef0f0a6f"},
   "captcha": {:git, "https://git.pleroma.social/pleroma/elixir-libraries/elixir-captcha.git", "e0f16822d578866e186a0974d65ad58cddc1e2ab", [ref: "e0f16822d578866e186a0974d65ad58cddc1e2ab"]},
   "castore": {:hex, :castore, "0.1.17", "ba672681de4e51ed8ec1f74ed624d104c0db72742ea1a5e74edbc770c815182f", [:mix], [], "hexpm", "d9844227ed52d26e7519224525cb6868650c272d4a3d327ce3ca5570c12163f9"},