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 index_operation() :: Operation.t()
  17   def index_operation do
  18     %Operation{
  19       tags: ["Applications"],
  20       summary: "List applications",
  21       description: "List the OAuth applications for the current user",
  22       operationId: "AppController.index",
  23       responses: %{
  24         200 => Operation.response("App", "application/json", index_response())
  25       }
  26     }
  27   end
  28
  29   @spec create_operation() :: Operation.t()
  30   def create_operation do
  31     %Operation{
  32       tags: ["Applications"],
  33       summary: "Create an application",
  34       description: "Create a new application to obtain OAuth2 credentials",
  35       operationId: "AppController.create",
  36       requestBody: Helpers.request_body("Parameters", create_request(), required: true),
  37       responses: %{
  38         200 => Operation.response("App", "application/json", create_response()),
  39         422 =>
  40           Operation.response(
  41             "Unprocessable Entity",
  42             "application/json",
  43             %Schema{
  44               type: :object,
  45               description:
  46                 "If a required parameter is missing or improperly formatted, the request will fail.",
  47               properties: %{
  48                 error: %Schema{type: :string}
  49               },
  50               example: %{
  51                 "error" => "Validation failed: Redirect URI must be an absolute URI."
  52               }
  53             }
  54           )
  55       }
  56     }
  57   end
  58
  59   def verify_credentials_operation do
  60     %Operation{
  61       tags: ["Applications"],
  62       summary: "Verify the application works",
  63       description: "Confirm that the app's OAuth2 credentials work.",
  64       operationId: "AppController.verify_credentials",
  65       security: [%{"oAuth" => ["read"]}],
  66       responses: %{
  67         200 =>
  68           Operation.response("App", "application/json", %Schema{
  69             type: :object,
  70             description:
  71               "If the Authorization header was provided with a valid token, you should see your app returned as an Application entity.",
  72             properties: %{
  73               name: %Schema{type: :string},
  74               vapid_key: %Schema{type: :string},
  75               website: %Schema{type: :string, nullable: true}
  76             },
  77             example: %{
  78               "name" => "My App",
  79               "vapid_key" =>
  80                 "BCk-QqERU0q-CfYZjcuB6lnyyOYfJ2AifKqfeGIm7Z-HiTU5T9eTG5GxVA0_OH5mMlI4UkkDTpaZwozy0TzdZ2M=",
  81               "website" => "https://myapp.com/"
  82             }
  83           }),
  84         422 =>
  85           Operation.response(
  86             "Unauthorized",
  87             "application/json",
  88             %Schema{
  89               type: :object,
  90               description:
  91                 "If the Authorization header contains an invalid token, is malformed, or is not present, an error will be returned indicating an authorization failure.",
  92               properties: %{
  93                 error: %Schema{type: :string}
  94               },
  95               example: %{
  96                 "error" => "The access token is invalid."
  97               }
  98             }
  99           )
 100       }
 101     }
 102   end
 103
 104   defp create_request do
 105     %Schema{
 106       title: "AppCreateRequest",
 107       description: "POST body for creating an app",
 108       type: :object,
 109       properties: %{
 110         client_name: %Schema{type: :string, description: "A name for your application."},
 111         redirect_uris: %Schema{
 112           type: :string,
 113           description:
 114             "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."
 115         },
 116         scopes: %Schema{
 117           type: :string,
 118           description: "Space separated list of scopes",
 119           default: "read"
 120         },
 121         website: %Schema{
 122           type: :string,
 123           nullable: true,
 124           description: "A URL to the homepage of your app"
 125         }
 126       },
 127       required: [:client_name, :redirect_uris],
 128       example: %{
 129         "client_name" => "My App",
 130         "redirect_uris" => "https://myapp.com/auth/callback",
 131         "website" => "https://myapp.com/"
 132       }
 133     }
 134   end
 135
 136   defp create_response do
 137     %Schema{
 138       title: "AppCreateResponse",
 139       description: "Response schema for an app",
 140       type: :object,
 141       properties: %{
 142         id: %Schema{type: :string},
 143         name: %Schema{type: :string},
 144         client_id: %Schema{type: :string},
 145         client_secret: %Schema{type: :string},
 146         redirect_uri: %Schema{type: :string},
 147         vapid_key: %Schema{type: :string},
 148         website: %Schema{type: :string, nullable: true}
 149       },
 150       example: %{
 151         "id" => "123",
 152         "name" => "My App",
 153         "client_id" => "TWhM-tNSuncnqN7DBJmoyeLnk6K3iJJ71KKXxgL1hPM",
 154         "client_secret" => "ZEaFUFmF0umgBX1qKJDjaU99Q31lDkOU8NutzTOoliw",
 155         "vapid_key" =>
 156           "BCk-QqERU0q-CfYZjcuB6lnyyOYfJ2AifKqfeGIm7Z-HiTU5T9eTG5GxVA0_OH5mMlI4UkkDTpaZwozy0TzdZ2M=",
 157         "website" => "https://myapp.com/"
 158       }
 159     }
 160   end
 161
 162   defp index_response do
 163     %Schema{
 164       title: "AppIndexResponse",
 165       description: "Response schema for GET /api/v1/apps",
 166       type: :object,
 167       properties: [
 168         %{
 169           id: %Schema{type: :string},
 170           name: %Schema{type: :string},
 171           client_id: %Schema{type: :string},
 172           client_secret: %Schema{type: :string},
 173           redirect_uri: %Schema{type: :string},
 174           vapid_key: %Schema{type: :string},
 175           website: %Schema{type: :string, nullable: true}
 176         }
 177       ],
 178       example: [
 179         %{
 180           "id" => "123",
 181           "name" => "My App",
 182           "client_id" => "TWhM-tNSuncnqN7DBJmoyeLnk6K3iJJ71KKXxgL1hPM",
 183           "client_secret" => "ZEaFUFmF0umgBX1qKJDjaU99Q31lDkOU8NutzTOoliw",
 184           "vapid_key" =>
 185             "BCk-QqERU0q-CfYZjcuB6lnyyOYfJ2AifKqfeGIm7Z-HiTU5T9eTG5GxVA0_OH5mMlI4UkkDTpaZwozy0TzdZ2M=",
 186           "website" => "https://myapp.com/"
 187         }
 188       ]
 189     }
 190   end
 191 end