git.squeep.com Git - akkoma/blob - lib/pleroma/web/api_spec/operations/filter_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.FilterOperation do
   6   alias OpenApiSpex.Operation
   7   alias OpenApiSpex.Schema
   8   alias Pleroma.Web.ApiSpec.Helpers
   9   alias Pleroma.Web.ApiSpec.Schemas.BooleanLike
  10
  11   def open_api_operation(action) do
  12     operation = String.to_existing_atom("#{action}_operation")
  13     apply(__MODULE__, operation, [])
  14   end
  15
  16   def index_operation do
  17     %Operation{
  18       tags: ["apps"],
  19       summary: "View all filters",
  20       operationId: "FilterController.index",
  21       security: [%{"oAuth" => ["read:filters"]}],
  22       responses: %{
  23         200 => Operation.response("Filters", "application/json", array_of_filters())
  24       }
  25     }
  26   end
  27
  28   def create_operation do
  29     %Operation{
  30       tags: ["apps"],
  31       summary: "Create a filter",
  32       operationId: "FilterController.create",
  33       requestBody: Helpers.request_body("Parameters", create_request(), required: true),
  34       security: [%{"oAuth" => ["write:filters"]}],
  35       responses: %{200 => Operation.response("Filter", "application/json", filter())}
  36     }
  37   end
  38
  39   def show_operation do
  40     %Operation{
  41       tags: ["apps"],
  42       summary: "View all filters",
  43       parameters: [id_param()],
  44       operationId: "FilterController.show",
  45       security: [%{"oAuth" => ["read:filters"]}],
  46       responses: %{
  47         200 => Operation.response("Filter", "application/json", filter())
  48       }
  49     }
  50   end
  51
  52   def update_operation do
  53     %Operation{
  54       tags: ["apps"],
  55       summary: "Update a filter",
  56       parameters: [id_param()],
  57       operationId: "FilterController.update",
  58       requestBody: Helpers.request_body("Parameters", update_request(), required: true),
  59       security: [%{"oAuth" => ["write:filters"]}],
  60       responses: %{
  61         200 => Operation.response("Filter", "application/json", filter())
  62       }
  63     }
  64   end
  65
  66   def delete_operation do
  67     %Operation{
  68       tags: ["apps"],
  69       summary: "Remove a filter",
  70       parameters: [id_param()],
  71       operationId: "FilterController.delete",
  72       security: [%{"oAuth" => ["write:filters"]}],
  73       responses: %{
  74         200 =>
  75           Operation.response("Filter", "application/json", %Schema{
  76             type: :object,
  77             description: "Empty object"
  78           })
  79       }
  80     }
  81   end
  82
  83   defp id_param do
  84     Operation.parameter(:id, :path, :string, "Filter ID", example: "123", required: true)
  85   end
  86
  87   defp filter do
  88     %Schema{
  89       title: "Filter",
  90       type: :object,
  91       properties: %{
  92         id: %Schema{type: :string},
  93         phrase: %Schema{type: :string, description: "The text to be filtered"},
  94         context: %Schema{
  95           type: :array,
  96           items: %Schema{type: :string, enum: ["home", "notifications", "public", "thread"]},
  97           description: "The contexts in which the filter should be applied."
  98         },
  99         expires_at: %Schema{
 100           type: :string,
 101           format: :"date-time",
 102           description:
 103             "When the filter should no longer be applied. String (ISO 8601 Datetime), or null if the filter does not expire.",
 104           nullable: true
 105         },
 106         irreversible: %Schema{
 107           type: :boolean,
 108           description:
 109             "Should matching entities in home and notifications be dropped by the server?"
 110         },
 111         whole_word: %Schema{
 112           type: :boolean,
 113           description: "Should the filter consider word boundaries?"
 114         }
 115       },
 116       example: %{
 117         "id" => "5580",
 118         "phrase" => "@twitter.com",
 119         "context" => [
 120           "home",
 121           "notifications",
 122           "public",
 123           "thread"
 124         ],
 125         "whole_word" => false,
 126         "expires_at" => nil,
 127         "irreversible" => true
 128       }
 129     }
 130   end
 131
 132   defp array_of_filters do
 133     %Schema{
 134       title: "ArrayOfFilters",
 135       description: "Array of Filters",
 136       type: :array,
 137       items: filter(),
 138       example: [
 139         %{
 140           "id" => "5580",
 141           "phrase" => "@twitter.com",
 142           "context" => [
 143             "home",
 144             "notifications",
 145             "public",
 146             "thread"
 147           ],
 148           "whole_word" => false,
 149           "expires_at" => nil,
 150           "irreversible" => true
 151         },
 152         %{
 153           "id" => "6191",
 154           "phrase" => ":eurovision2019:",
 155           "context" => [
 156             "home"
 157           ],
 158           "whole_word" => true,
 159           "expires_at" => "2019-05-21T13:47:31.333Z",
 160           "irreversible" => false
 161         }
 162       ]
 163     }
 164   end
 165
 166   defp create_request do
 167     %Schema{
 168       title: "FilterCreateRequest",
 169       allOf: [
 170         update_request(),
 171         %Schema{
 172           type: :object,
 173           properties: %{
 174             irreversible: %Schema{
 175               allOf: [BooleanLike],
 176               description:
 177                 "Should the server irreversibly drop matching entities from home and notifications?",
 178               default: false
 179             }
 180           }
 181         }
 182       ],
 183       example: %{
 184         "phrase" => "knights",
 185         "context" => ["home"]
 186       }
 187     }
 188   end
 189
 190   defp update_request do
 191     %Schema{
 192       title: "FilterUpdateRequest",
 193       type: :object,
 194       properties: %{
 195         phrase: %Schema{type: :string, description: "The text to be filtered"},
 196         context: %Schema{
 197           type: :array,
 198           items: %Schema{type: :string, enum: ["home", "notifications", "public", "thread"]},
 199           description:
 200             "Array of enumerable strings `home`, `notifications`, `public`, `thread`. At least one context must be specified."
 201         },
 202         irreversible: %Schema{
 203           allOf: [BooleanLike],
 204           nullable: true,
 205           description:
 206             "Should the server irreversibly drop matching entities from home and notifications?"
 207         },
 208         whole_word: %Schema{
 209           allOf: [BooleanLike],
 210           nullable: true,
 211           description: "Consider word boundaries?",
 212           default: true
 213         }
 214         # TODO: probably should implement filter expiration
 215         # expires_in: %Schema{
 216         #   type: :string,
 217         #   format: :"date-time",
 218         #   description:
 219         #     "ISO 8601 Datetime for when the filter expires. Otherwise,
 220         #  null for a filter that doesn't expire."
 221         # }
 222       },
 223       required: [:phrase, :context],
 224       example: %{
 225         "phrase" => "knights",
 226         "context" => ["home"]
 227       }
 228     }
 229   end
 230 end