akkoma/lib/pleroma/web/api_spec/operations/timeline_operation.ex
rinpatch e2d7c4fd57 Merge branch 'feat/openapi-spec-export' into 'develop'
Improve OpenAPI spec and deploy it to api.pleroma.social

See merge request pleroma/pleroma!3296
2021-02-03 13:21:19 +00:00

216 lines
6.1 KiB
Elixir

# Pleroma: A lightweight social networking server
# Copyright © 2017-2021 Pleroma Authors <https://pleroma.social/>
# SPDX-License-Identifier: AGPL-3.0-only
defmodule Pleroma.Web.ApiSpec.TimelineOperation do
alias OpenApiSpex.Operation
alias OpenApiSpex.Schema
alias Pleroma.Web.ApiSpec.Schemas.ApiError
alias Pleroma.Web.ApiSpec.Schemas.BooleanLike
alias Pleroma.Web.ApiSpec.Schemas.Status
alias Pleroma.Web.ApiSpec.Schemas.VisibilityScope
import Pleroma.Web.ApiSpec.Helpers
def open_api_operation(action) do
operation = String.to_existing_atom("#{action}_operation")
apply(__MODULE__, operation, [])
end
def home_operation do
%Operation{
tags: ["Timelines"],
summary: "Home timeline",
description: "View statuses from followed users",
security: [%{"oAuth" => ["read:statuses"]}],
parameters: [
local_param(),
remote_param(),
only_media_param(),
with_muted_param(),
exclude_visibilities_param(),
reply_visibility_param() | pagination_params()
],
operationId: "TimelineController.home",
responses: %{
200 => Operation.response("Array of Status", "application/json", array_of_statuses())
}
}
end
def direct_operation do
%Operation{
tags: ["Timelines"],
summary: "Direct timeline",
description:
"View statuses with a “direct” scope addressed to the account. Using this endpoint is discouraged, please use [conversations](#tag/Conversations) or [chats](#tag/Chats).",
parameters: [with_muted_param() | pagination_params()],
security: [%{"oAuth" => ["read:statuses"]}],
operationId: "TimelineController.direct",
responses: %{
200 => Operation.response("Array of Status", "application/json", array_of_statuses())
}
}
end
def public_operation do
%Operation{
tags: ["Timelines"],
summary: "Public timeline",
security: [%{"oAuth" => ["read:statuses"]}],
parameters: [
local_param(),
instance_param(),
only_media_param(),
remote_param(),
with_muted_param(),
exclude_visibilities_param(),
reply_visibility_param() | pagination_params()
],
operationId: "TimelineController.public",
responses: %{
200 => Operation.response("Array of Status", "application/json", array_of_statuses()),
401 => Operation.response("Error", "application/json", ApiError)
}
}
end
def hashtag_operation do
%Operation{
tags: ["Timelines"],
summary: "Hashtag timeline",
description: "View public statuses containing the given hashtag",
security: [%{"oAuth" => ["read:statuses"]}],
parameters: [
Operation.parameter(
:tag,
:path,
%Schema{type: :string},
"Content of a #hashtag, not including # symbol.",
required: true
),
Operation.parameter(
:any,
:query,
%Schema{type: :array, items: %Schema{type: :string}},
"Statuses that also includes any of these tags"
),
Operation.parameter(
:all,
:query,
%Schema{type: :array, items: %Schema{type: :string}},
"Statuses that also includes all of these tags"
),
Operation.parameter(
:none,
:query,
%Schema{type: :array, items: %Schema{type: :string}},
"Statuses that do not include these tags"
),
local_param(),
only_media_param(),
remote_param(),
with_muted_param(),
exclude_visibilities_param() | pagination_params()
],
operationId: "TimelineController.hashtag",
responses: %{
200 => Operation.response("Array of Status", "application/json", array_of_statuses())
}
}
end
def list_operation do
%Operation{
tags: ["Timelines"],
summary: "List timeline",
description: "View statuses in the given list timeline",
security: [%{"oAuth" => ["read:lists"]}],
parameters: [
Operation.parameter(
:list_id,
:path,
%Schema{type: :string},
"Local ID of the list in the database",
required: true
),
with_muted_param(),
local_param(),
remote_param(),
only_media_param(),
exclude_visibilities_param() | pagination_params()
],
operationId: "TimelineController.list",
responses: %{
200 => Operation.response("Array of Status", "application/json", array_of_statuses())
}
}
end
defp array_of_statuses do
%Schema{
title: "ArrayOfStatuses",
type: :array,
items: Status,
example: [Status.schema().example]
}
end
defp local_param do
Operation.parameter(
:local,
:query,
%Schema{allOf: [BooleanLike], default: false},
"Show only local statuses?"
)
end
defp instance_param do
Operation.parameter(
:instance,
:query,
%Schema{type: :string},
"Show only statuses from the given domain"
)
end
defp with_muted_param do
Operation.parameter(:with_muted, :query, BooleanLike, "Include activities by muted users")
end
defp exclude_visibilities_param do
Operation.parameter(
:exclude_visibilities,
:query,
%Schema{type: :array, items: VisibilityScope},
"Exclude the statuses with the given visibilities"
)
end
defp reply_visibility_param do
Operation.parameter(
:reply_visibility,
:query,
%Schema{type: :string, enum: ["following", "self"]},
"Filter replies. Possible values: without parameter (default) shows all replies, `following` - replies directed to you or users you follow, `self` - replies directed to you."
)
end
defp only_media_param do
Operation.parameter(
:only_media,
:query,
%Schema{allOf: [BooleanLike], default: false},
"Show only statuses with media attached?"
)
end
defp remote_param do
Operation.parameter(
:remote,
:query,
%Schema{allOf: [BooleanLike], default: false},
"Show only remote statuses?"
)
end
end