From 37ae047e1652c4089934434ec79f393c4c839122 Mon Sep 17 00:00:00 2001 From: floatingghost Date: Wed, 13 Jul 2022 15:09:35 +0000 Subject: [PATCH] Add swaggerUI options (#66) Reviewed-on: https://akkoma.dev/AkkomaGang/akkoma/pulls/66 --- config/config.exs | 13 +++++ config/description.exs | 15 ++++++ docs/configuration/cheatsheet.md | 61 ++++++++++------------- docs/configuration/frontend_management.md | 60 ++++++++++++++++++++++ lib/akkoma/web/swagger.ex | 7 +++ lib/pleroma/application.ex | 12 ++++- lib/pleroma/web/endpoint.ex | 7 +-- lib/pleroma/web/plugs/frontend_static.ex | 2 + mix.exs | 2 +- mix.lock | 2 +- 10 files changed, 141 insertions(+), 40 deletions(-) create mode 100644 docs/configuration/frontend_management.md create mode 100644 lib/akkoma/web/swagger.ex diff --git a/config/config.exs b/config/config.exs index 6123828b5..dddb5cea5 100644 --- a/config/config.exs +++ b/config/config.exs @@ -719,6 +719,11 @@ config :pleroma, :static_fe, enabled: false 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 @@ config :pleroma, :frontends, "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" } } diff --git a/config/description.exs b/config/description.exs index c36e9d2b2..098a6f5b7 100644 --- a/config/description.exs +++ b/config/description.exs @@ -3089,6 +3089,21 @@ config :pleroma, :config_description, [ 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, diff --git a/docs/configuration/cheatsheet.md b/docs/configuration/cheatsheet.md index 27f43690b..17da58594 100644 --- a/docs/configuration/cheatsheet.md +++ b/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 diff --git a/docs/configuration/frontend_management.md b/docs/configuration/frontend_management.md new file mode 100644 index 000000000..a95d50aa8 --- /dev/null +++ b/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` diff --git a/lib/akkoma/web/swagger.ex b/lib/akkoma/web/swagger.ex new file mode 100644 index 000000000..c09cba3a1 --- /dev/null +++ b/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 diff --git a/lib/pleroma/application.ex b/lib/pleroma/application.ex index fcb1d6571..5801e930d 100644 --- a/lib/pleroma/application.ex +++ b/lib/pleroma/application.ex @@ -82,7 +82,17 @@ defmodule Pleroma.Application 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() diff --git a/lib/pleroma/web/endpoint.ex b/lib/pleroma/web/endpoint.ex index 1052c235c..4a235fdd7 100644 --- a/lib/pleroma/web/endpoint.ex +++ b/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", - frontend_type: :fedife, + at: "/akkoma/swaggerui", + 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 diff --git a/lib/pleroma/web/plugs/frontend_static.ex b/lib/pleroma/web/plugs/frontend_static.ex index ebe7eaf86..5d9ae2ff7 100644 --- a/lib/pleroma/web/plugs/frontend_static.ex +++ b/lib/pleroma/web/plugs/frontend_static.ex @@ -31,11 +31,13 @@ defmodule Pleroma.Web.Plugs.FrontendStatic 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) diff --git a/mix.exs b/mix.exs index 0bd6ea4e7..c255be1db 100644 --- a/mix.exs +++ b/mix.exs @@ -133,7 +133,7 @@ defmodule Pleroma.Mixfile 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"}, diff --git a/mix.lock b/mix.lock index 0c3ca8992..8cd6f8255 100644 --- a/mix.lock +++ b/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"},