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