git.squeep.com Git - akkoma/blob - lib/pleroma/web/api_spec.ex

   1 # Pleroma: A lightweight social networking server
   2 # Copyright © 2017-2021 Pleroma Authors <https://pleroma.social/>
   3 # SPDX-License-Identifier: AGPL-3.0-only
   4
   5 defmodule Pleroma.Web.ApiSpec do
   6   alias OpenApiSpex.OpenApi
   7   alias OpenApiSpex.Operation
   8   alias Pleroma.Web.Endpoint
   9   alias Pleroma.Web.Router
  10
  11   @behaviour OpenApi
  12
  13   @impl OpenApi
  14   def spec(opts \\ []) do
  15     %OpenApi{
  16       servers:
  17         if opts[:server_specific] do
  18           [
  19             # Populate the Server info from a phoenix endpoint
  20             OpenApiSpex.Server.from_endpoint(Endpoint)
  21           ]
  22         else
  23           []
  24         end,
  25       info: %OpenApiSpex.Info{
  26         title: "Pleroma API",
  27         description: """
  28         This is documentation for client Pleroma API. Most of the endpoints and entities come
  29         from Mastodon API and have custom extensions on top.
  30
  31         While this document aims to be a complete guide to the client API Pleroma exposes,
  32         the details are still being worked out. Some endpoints may have incomplete or poorly worded documentation.
  33         You might want to check the following resources if something is not clear:
  34         - [Legacy Pleroma-specific endpoint documentation](https://docs-develop.pleroma.social/backend/development/API/pleroma_api/)
  35         - [Mastodon API documentation](https://docs.joinmastodon.org/client/intro/)
  36         - [Differences in Mastodon API responses from vanilla Mastodon](https://docs-develop.pleroma.social/backend/development/API/differences_in_mastoapi_responses/)
  37
  38         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!
  39         """,
  40         # Strip environment from the version
  41         version: Application.spec(:pleroma, :vsn) |> to_string() |> String.replace(~r/\+.*$/, ""),
  42         extensions: %{
  43           # Logo path should be picked so that the path exists both on Pleroma instances and on api.pleroma.social
  44           "x-logo": %{"url" => "/static/logo.svg", "altText" => "Pleroma logo"}
  45         }
  46       },
  47       # populate the paths from a phoenix router
  48       paths: OpenApiSpex.Paths.from_router(Router),
  49       components: %OpenApiSpex.Components{
  50         parameters: %{
  51           "accountIdOrNickname" =>
  52             Operation.parameter(:id, :path, :string, "Account ID or nickname",
  53               example: "123",
  54               required: true
  55             )
  56         },
  57         securitySchemes: %{
  58           "oAuth" => %OpenApiSpex.SecurityScheme{
  59             type: "oauth2",
  60             flows: %OpenApiSpex.OAuthFlows{
  61               password: %OpenApiSpex.OAuthFlow{
  62                 authorizationUrl: "/oauth/authorize",
  63                 tokenUrl: "/oauth/token",
  64                 scopes: %{
  65                   # TODO: Document granular scopes
  66                   "read" => "Read everything",
  67                   "write" => "Write everything",
  68                   "follow" => "Manage relationships",
  69                   "push" => "Web Push API subscriptions"
  70                 }
  71               }
  72             }
  73           }
  74         }
  75       },
  76       extensions: %{
  77         # Redoc-specific extension, every time a new tag is added it should be reflected here,
  78         # otherwise it won't be shown.
  79         "x-tagGroups": [
  80           %{
  81             "name" => "Accounts",
  82             "tags" => ["Account actions", "Retrieve account information", "Scrobbles"]
  83           },
  84           %{
  85             "name" => "Administration",
  86             "tags" => [
  87               "Chat administration",
  88               "Emoji pack administration",
  89               "Frontend managment",
  90               "Instance configuration",
  91               "Instance documents",
  92               "Invites",
  93               "MediaProxy cache",
  94               "OAuth application managment",
  95               "Relays",
  96               "Report managment",
  97               "Status administration",
  98               "User administration"
  99             ]
 100           },
 101           %{"name" => "Applications", "tags" => ["Applications", "Push subscriptions"]},
 102           %{
 103             "name" => "Current account",
 104             "tags" => [
 105               "Account credentials",
 106               "Backups",
 107               "Blocks and mutes",
 108               "Data import",
 109               "Domain blocks",
 110               "Follow requests",
 111               "Mascot",
 112               "Markers",
 113               "Notifications"
 114             ]
 115           },
 116           %{"name" => "Instance", "tags" => ["Custom emojis"]},
 117           %{"name" => "Messaging", "tags" => ["Chats", "Conversations"]},
 118           %{
 119             "name" => "Statuses",
 120             "tags" => [
 121               "Emoji reactions",
 122               "Lists",
 123               "Polls",
 124               "Timelines",
 125               "Retrieve status information",
 126               "Scheduled statuses",
 127               "Search",
 128               "Status actions"
 129             ]
 130           },
 131           %{"name" => "Miscellaneous", "tags" => ["Emoji packs", "Reports", "Suggestions"]}
 132         ]
 133       }
 134     }
 135     # discover request/response schemas from path specs
 136     |> OpenApiSpex.resolve_schema_modules()
 137   end
 138 end