git.squeep.com Git - akkoma/blob - lib/pleroma/web/api_spec/helpers.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.Helpers do
   6   alias OpenApiSpex.Operation
   7   alias OpenApiSpex.Schema
   8   alias Pleroma.Web.ApiSpec.Schemas.BooleanLike
   9
  10   def request_body(description, schema_ref, opts \\ []) do
  11     media_types = ["application/json", "multipart/form-data", "application/x-www-form-urlencoded"]
  12
  13     content =
  14       media_types
  15       |> Enum.map(fn type ->
  16         {type,
  17          %OpenApiSpex.MediaType{
  18            schema: schema_ref,
  19            example: opts[:example],
  20            examples: opts[:examples]
  21          }}
  22       end)
  23       |> Enum.into(%{})
  24
  25     %OpenApiSpex.RequestBody{
  26       description: description,
  27       content: content,
  28       required: opts[:required] || false
  29     }
  30   end
  31
  32   def admin_api_params do
  33     [Operation.parameter(:admin_token, :query, :string, "Allows authorization via admin token.")]
  34   end
  35
  36   def pagination_params do
  37     [
  38       Operation.parameter(:max_id, :query, :string, "Return items older than this ID"),
  39       Operation.parameter(:min_id, :query, :string, "Return the oldest items newer than this ID"),
  40       Operation.parameter(
  41         :since_id,
  42         :query,
  43         :string,
  44         "Return the newest items newer than this ID"
  45       ),
  46       Operation.parameter(
  47         :offset,
  48         :query,
  49         %Schema{type: :integer, default: 0},
  50         "Return items past this number of items"
  51       ),
  52       Operation.parameter(
  53         :limit,
  54         :query,
  55         %Schema{type: :integer, default: 20},
  56         "Maximum number of items to return. Will be ignored if it's more than 40"
  57       )
  58     ]
  59   end
  60
  61   def with_relationships_param do
  62     Operation.parameter(
  63       :with_relationships,
  64       :query,
  65       BooleanLike,
  66       "Embed relationships into accounts. **If this parameter is not set account's `pleroma.relationship` is going to be `null`.**"
  67     )
  68   end
  69
  70   def empty_object_response do
  71     Operation.response("Empty object", "application/json", %Schema{type: :object, example: %{}})
  72   end
  73
  74   def empty_array_response do
  75     Operation.response("Empty array", "application/json", %Schema{
  76       type: :array,
  77       items: %Schema{type: :object, example: %{}},
  78       example: []
  79     })
  80   end
  81
  82   def no_content_response do
  83     Operation.response("No Content", "application/json", %Schema{type: :string, example: ""})
  84   end
  85 end