1 # Pleroma: A lightweight social networking server
2 # Copyright © 2017-2021 Pleroma Authors <https://pleroma.social/>
3 # SPDX-License-Identifier: AGPL-3.0-only
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
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, [])
17 @spec index_operation() :: Operation.t()
18 def index_operation do
20 tags: ["Applications"],
21 summary: "List applications",
22 description: "List the OAuth applications for the current user",
23 operationId: "AppController.index",
25 200 => Operation.response("Array of App", "application/json", array_of_apps())
30 @spec create_operation() :: Operation.t()
31 def create_operation do
33 tags: ["Applications"],
34 summary: "Create an application",
35 description: "Create a new application to obtain OAuth2 credentials",
36 operationId: "AppController.create",
37 requestBody: Helpers.request_body("Parameters", create_request(), required: true),
39 200 => create_response(),
42 "Unprocessable Entity",
47 "If a required parameter is missing or improperly formatted, the request will fail.",
49 error: %Schema{type: :string}
52 "error" => "Validation failed: Redirect URI must be an absolute URI."
60 def verify_credentials_operation do
62 tags: ["Applications"],
63 summary: "Verify the application works",
64 description: "Confirm that the app's OAuth2 credentials work.",
65 operationId: "AppController.verify_credentials",
66 security: [%{"oAuth" => ["read"]}],
69 Operation.response("App", "application/json", %Schema{
72 "If the Authorization header was provided with a valid token, you should see your app returned as an Application entity.",
74 name: %Schema{type: :string},
75 vapid_key: %Schema{type: :string},
76 website: %Schema{type: :string, nullable: true}
81 "BCk-QqERU0q-CfYZjcuB6lnyyOYfJ2AifKqfeGIm7Z-HiTU5T9eTG5GxVA0_OH5mMlI4UkkDTpaZwozy0TzdZ2M=",
82 "website" => "https://myapp.com/"
92 "If the Authorization header contains an invalid token, is malformed, or is not present, an error will be returned indicating an authorization failure.",
94 error: %Schema{type: :string}
97 "error" => "The access token is invalid."
105 defp create_request do
107 title: "AppCreateRequest",
108 description: "POST body for creating an app",
111 client_name: %Schema{type: :string, description: "A name for your application."},
112 redirect_uris: %Schema{
115 "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."
119 description: "Space separated list of scopes",
125 description: "A URL to the homepage of your app"
128 required: [:client_name, :redirect_uris],
130 "client_name" => "My App",
131 "redirect_uris" => "https://myapp.com/auth/callback",
132 "website" => "https://myapp.com/"
137 defp create_response do
138 Operation.response("App", "application/json", App)
141 defp array_of_apps do
142 %Schema{type: :array, items: App, example: [App.schema().example]}