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

   1 # Pleroma: A lightweight social networking server
   2 # Copyright © 2017-2020 Pleroma Authors <https://pleroma.social/>
   3 # SPDX-License-Identifier: AGPL-3.0-only
   4
   5 defmodule Pleroma.Web.ApiSpec.AppOperation do
   6   alias OpenApiSpex.Operation
   7   alias OpenApiSpex.Schema
   8   alias Pleroma.Web.ApiSpec.Helpers
   9   alias Pleroma.Web.ApiSpec.Schemas.AppCreateRequest
  10   alias Pleroma.Web.ApiSpec.Schemas.AppCreateResponse
  11
  12   @spec open_api_operation(atom) :: Operation.t()
  13   def open_api_operation(action) do
  14     operation = String.to_existing_atom("#{action}_operation")
  15     apply(__MODULE__, operation, [])
  16   end
  17
  18   @spec create_operation() :: Operation.t()
  19   def create_operation do
  20     %Operation{
  21       tags: ["apps"],
  22       summary: "Create an application",
  23       description: "Create a new application to obtain OAuth2 credentials",
  24       operationId: "AppController.create",
  25       requestBody: Helpers.request_body("Parameters", AppCreateRequest, required: true),
  26       responses: %{
  27         200 => Operation.response("App", "application/json", AppCreateResponse),
  28         422 =>
  29           Operation.response(
  30             "Unprocessable Entity",
  31             "application/json",
  32             %Schema{
  33               type: :object,
  34               description:
  35                 "If a required parameter is missing or improperly formatted, the request will fail.",
  36               properties: %{
  37                 error: %Schema{type: :string}
  38               },
  39               example: %{
  40                 "error" => "Validation failed: Redirect URI must be an absolute URI."
  41               }
  42             }
  43           )
  44       }
  45     }
  46   end
  47
  48   def verify_credentials_operation do
  49     %Operation{
  50       tags: ["apps"],
  51       summary: "Verify your app works",
  52       description: "Confirm that the app's OAuth2 credentials work.",
  53       operationId: "AppController.verify_credentials",
  54       security: [
  55         %{
  56           "oAuth" => ["read"]
  57         }
  58       ],
  59       responses: %{
  60         200 =>
  61           Operation.response("App", "application/json", %Schema{
  62             type: :object,
  63             description:
  64               "If the Authorization header was provided with a valid token, you should see your app returned as an Application entity.",
  65             properties: %{
  66               name: %Schema{type: :string},
  67               vapid_key: %Schema{type: :string},
  68               website: %Schema{type: :string, nullable: true}
  69             },
  70             example: %{
  71               "name" => "My App",
  72               "vapid_key" =>
  73                 "BCk-QqERU0q-CfYZjcuB6lnyyOYfJ2AifKqfeGIm7Z-HiTU5T9eTG5GxVA0_OH5mMlI4UkkDTpaZwozy0TzdZ2M=",
  74               "website" => "https://myapp.com/"
  75             }
  76           }),
  77         422 =>
  78           Operation.response(
  79             "Unauthorized",
  80             "application/json",
  81             %Schema{
  82               type: :object,
  83               description:
  84                 "If the Authorization header contains an invalid token, is malformed, or is not present, an error will be returned indicating an authorization failure.",
  85               properties: %{
  86                 error: %Schema{type: :string}
  87               },
  88               example: %{
  89                 "error" => "The access token is invalid."
  90               }
  91             }
  92           )
  93       }
  94     }
  95   end
  96 end