git.squeep.com Git - akkoma/blob - lib/pleroma/web/api_spec/operations/admin/oauth_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.Admin.OAuthAppOperation do
   6   alias OpenApiSpex.Operation
   7   alias OpenApiSpex.Schema
   8   alias Pleroma.Web.ApiSpec.Schemas.ApiError
   9
  10   import Pleroma.Web.ApiSpec.Helpers
  11
  12   def open_api_operation(action) do
  13     operation = String.to_existing_atom("#{action}_operation")
  14     apply(__MODULE__, operation, [])
  15   end
  16
  17   def index_operation do
  18     %Operation{
  19       summary: "List OAuth apps",
  20       tags: ["Admin", "oAuth Apps"],
  21       operationId: "AdminAPI.OAuthAppController.index",
  22       security: [%{"oAuth" => ["write"]}],
  23       parameters: [
  24         Operation.parameter(:name, :query, %Schema{type: :string}, "App name"),
  25         Operation.parameter(:client_id, :query, %Schema{type: :string}, "Client ID"),
  26         Operation.parameter(:page, :query, %Schema{type: :integer, default: 1}, "Page"),
  27         Operation.parameter(
  28           :trusted,
  29           :query,
  30           %Schema{type: :boolean, default: false},
  31           "Trusted apps"
  32         ),
  33         Operation.parameter(
  34           :page_size,
  35           :query,
  36           %Schema{type: :integer, default: 50},
  37           "Number of apps to return"
  38         )
  39       ],
  40       responses: %{
  41         200 =>
  42           Operation.response("List of apps", "application/json", %Schema{
  43             type: :object,
  44             properties: %{
  45               apps: %Schema{type: :array, items: oauth_app()},
  46               count: %Schema{type: :integer},
  47               page_size: %Schema{type: :integer}
  48             },
  49             example: %{
  50               "apps" => [
  51                 %{
  52                   "id" => 1,
  53                   "name" => "App name",
  54                   "client_id" => "yHoDSiWYp5mPV6AfsaVOWjdOyt5PhWRiafi6MRd1lSk",
  55                   "client_secret" => "nLmis486Vqrv2o65eM9mLQx_m_4gH-Q6PcDpGIMl6FY",
  56                   "redirect_uri" => "https://example.com/oauth-callback",
  57                   "website" => "https://example.com",
  58                   "trusted" => true
  59                 }
  60               ],
  61               "count" => 1,
  62               "page_size" => 50
  63             }
  64           })
  65       }
  66     }
  67   end
  68
  69   def create_operation do
  70     %Operation{
  71       tags: ["Admin", "oAuth Apps"],
  72       summary: "Create OAuth App",
  73       operationId: "AdminAPI.OAuthAppController.create",
  74       requestBody: request_body("Parameters", create_request()),
  75       security: [%{"oAuth" => ["write"]}],
  76       responses: %{
  77         200 => Operation.response("App", "application/json", oauth_app()),
  78         400 => Operation.response("Bad Request", "application/json", ApiError)
  79       }
  80     }
  81   end
  82
  83   def update_operation do
  84     %Operation{
  85       tags: ["Admin", "oAuth Apps"],
  86       summary: "Update OAuth App",
  87       operationId: "AdminAPI.OAuthAppController.update",
  88       parameters: [id_param()],
  89       security: [%{"oAuth" => ["write"]}],
  90       requestBody: request_body("Parameters", update_request()),
  91       responses: %{
  92         200 => Operation.response("App", "application/json", oauth_app()),
  93         400 =>
  94           Operation.response("Bad Request", "application/json", %Schema{
  95             oneOf: [ApiError, %Schema{type: :string}]
  96           })
  97       }
  98     }
  99   end
 100
 101   def delete_operation do
 102     %Operation{
 103       tags: ["Admin", "oAuth Apps"],
 104       summary: "Delete OAuth App",
 105       operationId: "AdminAPI.OAuthAppController.delete",
 106       parameters: [id_param()],
 107       security: [%{"oAuth" => ["write"]}],
 108       responses: %{
 109         204 => no_content_response(),
 110         400 => no_content_response()
 111       }
 112     }
 113   end
 114
 115   defp create_request do
 116     %Schema{
 117       title: "oAuthAppCreateRequest",
 118       type: :object,
 119       required: [:name, :redirect_uris],
 120       properties: %{
 121         name: %Schema{type: :string, description: "Application Name"},
 122         scopes: %Schema{type: :array, items: %Schema{type: :string}, description: "oAuth scopes"},
 123         redirect_uris: %Schema{
 124           type: :string,
 125           description:
 126             "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."
 127         },
 128         website: %Schema{
 129           type: :string,
 130           nullable: true,
 131           description: "A URL to the homepage of the app"
 132         },
 133         trusted: %Schema{
 134           type: :boolean,
 135           nullable: true,
 136           default: false,
 137           description: "Is the app trusted?"
 138         }
 139       },
 140       example: %{
 141         "name" => "My App",
 142         "redirect_uris" => "https://myapp.com/auth/callback",
 143         "website" => "https://myapp.com/",
 144         "scopes" => ["read", "write"],
 145         "trusted" => true
 146       }
 147     }
 148   end
 149
 150   defp update_request do
 151     %Schema{
 152       title: "oAuthAppUpdateRequest",
 153       type: :object,
 154       properties: %{
 155         name: %Schema{type: :string, description: "Application Name"},
 156         scopes: %Schema{type: :array, items: %Schema{type: :string}, description: "oAuth scopes"},
 157         redirect_uris: %Schema{
 158           type: :string,
 159           description:
 160             "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."
 161         },
 162         website: %Schema{
 163           type: :string,
 164           nullable: true,
 165           description: "A URL to the homepage of the app"
 166         },
 167         trusted: %Schema{
 168           type: :boolean,
 169           nullable: true,
 170           default: false,
 171           description: "Is the app trusted?"
 172         }
 173       },
 174       example: %{
 175         "name" => "My App",
 176         "redirect_uris" => "https://myapp.com/auth/callback",
 177         "website" => "https://myapp.com/",
 178         "scopes" => ["read", "write"],
 179         "trusted" => true
 180       }
 181     }
 182   end
 183
 184   defp oauth_app do
 185     %Schema{
 186       title: "oAuthApp",
 187       type: :object,
 188       properties: %{
 189         id: %Schema{type: :integer},
 190         name: %Schema{type: :string},
 191         client_id: %Schema{type: :string},
 192         client_secret: %Schema{type: :string},
 193         redirect_uri: %Schema{type: :string},
 194         website: %Schema{type: :string, nullable: true},
 195         trusted: %Schema{type: :boolean}
 196       },
 197       example: %{
 198         "id" => 123,
 199         "name" => "My App",
 200         "client_id" => "TWhM-tNSuncnqN7DBJmoyeLnk6K3iJJ71KKXxgL1hPM",
 201         "client_secret" => "ZEaFUFmF0umgBX1qKJDjaU99Q31lDkOU8NutzTOoliw",
 202         "redirect_uri" => "https://myapp.com/oauth-callback",
 203         "website" => "https://myapp.com/",
 204         "trusted" => false
 205       }
 206     }
 207   end
 208
 209   def id_param do
 210     Operation.parameter(:id, :path, :integer, "App ID",
 211       example: 1337,
 212       required: true
 213     )
 214   end
 215 end