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