sam/pleroma
sam/pleroma
1
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

Add swaggerUI options (#66)

Browse source 
Reviewed-on: https://akkoma.dev/AkkomaGang/akkoma/pulls/66
This commit is contained in:
floatingghost 2022-07-13 15:09:35 +00:00
parent 7c1a2092ca
commit 37ae047e16
10 changed files with 141 additions and 40 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

13
config/config.exs
View file

@ -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"
}
}

15
config/description.exs
View file

@ -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,

61
docs/configuration/cheatsheet.md
View file

@ -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

60
docs/configuration/frontend_management.md Normal file
View file

@ -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`

7
lib/akkoma/web/swagger.ex Normal file
View file

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

12
lib/pleroma/application.ex
View file

@ -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()

7
lib/pleroma/web/endpoint.ex
View file

@ -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

2
lib/pleroma/web/plugs/frontend_static.ex
View file

@ -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)

2
mix.exs
View file

@ -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"},

2
mix.lock
View file

@ -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"},