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-2021 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
  10   @spec open_api_operation(atom) :: Operation.t()
  11   def open_api_operation(action) do
  12     operation = String.to_existing_atom("#{action}_operation")
  13     apply(__MODULE__, operation, [])
  14   end
  15
  16   @spec create_operation() :: Operation.t()
  17   def create_operation do
  18     %Operation{
  19       tags: ["Applications"],
  20       summary: "Create an application",
  21       description: "Create a new application to obtain OAuth2 credentials",
  22       operationId: "AppController.create",
  23       requestBody: Helpers.request_body("Parameters", create_request(), required: true),
  24       responses: %{
  25         200 => Operation.response("App", "application/json", create_response()),
  26         422 =>
  27           Operation.response(
  28             "Unprocessable Entity",
  29             "application/json",
  30             %Schema{
  31               type: :object,
  32               description:
  33                 "If a required parameter is missing or improperly formatted, the request will fail.",
  34               properties: %{
  35                 error: %Schema{type: :string}
  36               },
  37               example: %{
  38                 "error" => "Validation failed: Redirect URI must be an absolute URI."
  39               }
  40             }
  41           )
  42       }
  43     }
  44   end
  45
  46   def verify_credentials_operation do
  47     %Operation{
  48       tags: ["Applications"],
  49       summary: "Verify the application works",
  50       description: "Confirm that the app's OAuth2 credentials work.",
  51       operationId: "AppController.verify_credentials",
  52       security: [%{"oAuth" => ["read"]}],
  53       responses: %{
  54         200 =>
  55           Operation.response("App", "application/json", %Schema{
  56             type: :object,
  57             description:
  58               "If the Authorization header was provided with a valid token, you should see your app returned as an Application entity.",
  59             properties: %{
  60               name: %Schema{type: :string},
  61               vapid_key: %Schema{type: :string},
  62               website: %Schema{type: :string, nullable: true}
  63             },
  64             example: %{
  65               "name" => "My App",
  66               "vapid_key" =>
  67                 "BCk-QqERU0q-CfYZjcuB6lnyyOYfJ2AifKqfeGIm7Z-HiTU5T9eTG5GxVA0_OH5mMlI4UkkDTpaZwozy0TzdZ2M=",
  68               "website" => "https://myapp.com/"
  69             }
  70           }),
  71         422 =>
  72           Operation.response(
  73             "Unauthorized",
  74             "application/json",
  75             %Schema{
  76               type: :object,
  77               description:
  78                 "If the Authorization header contains an invalid token, is malformed, or is not present, an error will be returned indicating an authorization failure.",
  79               properties: %{
  80                 error: %Schema{type: :string}
  81               },
  82               example: %{
  83                 "error" => "The access token is invalid."
  84               }
  85             }
  86           )
  87       }
  88     }
  89   end
  90
  91   defp create_request do
  92     %Schema{
  93       title: "AppCreateRequest",
  94       description: "POST body for creating an app",
  95       type: :object,
  96       properties: %{
  97         client_name: %Schema{type: :string, description: "A name for your application."},
  98         redirect_uris: %Schema{
  99           type: :string,
 100           description:
 101             "Where the user should be redirected after authorization. To display the authorization code to the user instead of redirecting to a web page, use `urn:ietf:wg:oauth:2.0:oob` in this parameter."
 102         },
 103         scopes: %Schema{
 104           type: :string,
 105           description: "Space separated list of scopes",
 106           default: "read"
 107         },
 108         website: %Schema{
 109           type: :string,
 110           nullable: true,
 111           description: "A URL to the homepage of your app"
 112         }
 113       },
 114       required: [:client_name, :redirect_uris],
 115       example: %{
 116         "client_name" => "My App",
 117         "redirect_uris" => "https://myapp.com/auth/callback",
 118         "website" => "https://myapp.com/"
 119       }
 120     }
 121   end
 122
 123   defp create_response do
 124     %Schema{
 125       title: "AppCreateResponse",
 126       description: "Response schema for an app",
 127       type: :object,
 128       properties: %{
 129         id: %Schema{type: :string},
 130         name: %Schema{type: :string},
 131         client_id: %Schema{type: :string},
 132         client_secret: %Schema{type: :string},
 133         redirect_uri: %Schema{type: :string},
 134         vapid_key: %Schema{type: :string},
 135         website: %Schema{type: :string, nullable: true}
 136       },
 137       example: %{
 138         "id" => "123",
 139         "name" => "My App",
 140         "client_id" => "TWhM-tNSuncnqN7DBJmoyeLnk6K3iJJ71KKXxgL1hPM",
 141         "client_secret" => "ZEaFUFmF0umgBX1qKJDjaU99Q31lDkOU8NutzTOoliw",
 142         "vapid_key" =>
 143           "BCk-QqERU0q-CfYZjcuB6lnyyOYfJ2AifKqfeGIm7Z-HiTU5T9eTG5GxVA0_OH5mMlI4UkkDTpaZwozy0TzdZ2M=",
 144         "website" => "https://myapp.com/"
 145       }
 146     }
 147   end
 148 end