X-Git-Url: https://git.squeep.com/?a=blobdiff_plain;f=lib%2Fpleroma%2Fweb%2Fapi_spec.ex;h=528cd9cf4fc43eeddbc760874322c2c4a4dd86b8;hb=3949cfdc249bb508c1171851fa2ec076126003cc;hp=41e48a0850a5bcd48cdd77e0aba92fd64e68d146;hpb=648cc699e551324a067cd1b906df5f497ade5861;p=akkoma
diff --git a/lib/pleroma/web/api_spec.ex b/lib/pleroma/web/api_spec.ex
index 41e48a085..528cd9cf4 100644
--- a/lib/pleroma/web/api_spec.ex
+++ b/lib/pleroma/web/api_spec.ex
@@ -1,29 +1,59 @@
# Pleroma: A lightweight social networking server
-# Copyright © 2017-2020 Pleroma Authors
+# Copyright © 2017-2021 Pleroma Authors
# SPDX-License-Identifier: AGPL-3.0-only
defmodule Pleroma.Web.ApiSpec do
alias OpenApiSpex.OpenApi
+ alias OpenApiSpex.Operation
alias Pleroma.Web.Endpoint
alias Pleroma.Web.Router
@behaviour OpenApi
@impl OpenApi
- def spec do
+ def spec(opts \\ []) do
%OpenApi{
- servers: [
- # Populate the Server info from a phoenix endpoint
- OpenApiSpex.Server.from_endpoint(Endpoint)
- ],
+ servers:
+ if opts[:server_specific] do
+ [
+ # Populate the Server info from a phoenix endpoint
+ OpenApiSpex.Server.from_endpoint(Endpoint)
+ ]
+ else
+ []
+ 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),
components: %OpenApiSpex.Components{
+ parameters: %{
+ "accountIdOrNickname" =>
+ Operation.parameter(:id, :path, :string, "Account ID or nickname",
+ example: "123",
+ required: true
+ )
+ },
securitySchemes: %{
"oAuth" => %OpenApiSpex.SecurityScheme{
type: "oauth2",
@@ -31,11 +61,75 @@ defmodule Pleroma.Web.ApiSpec do
password: %OpenApiSpex.OAuthFlow{
authorizationUrl: "/oauth/authorize",
tokenUrl: "/oauth/token",
- scopes: %{"read" => "read"}
+ scopes: %{
+ # 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",
+ "Relays",
+ "Report managment",
+ "Status administration",
+ "User 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