erin/akkoma
1
0
Fork 0
forked from mirrors/akkoma
Code Activity

Improve OpenAPI spec and deploy it to api.pleroma.social

Browse source 
Too many changes in OpenAPI spec to describe each one, but
basically it is tag fixes, bringing consitency to operation summaries
and fixing some incorrect information.
This commit is contained in:
rinpatch 2021-02-03 15:38:59 +03:00
parent ba40af054c
commit 9fcff7851f
39 changed files with 334 additions and 229 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

19
.gitlab-ci.yml
View file

@ -34,6 +34,14 @@ build:
- mix deps.get - mix deps.get
- mix compile --force - mix compile --force
spec-build:
stage: test
artifacts:
paths:
- spec.json
script:
- mix pleroma.openapi_spec spec.json
benchmark: benchmark:
stage: benchmark stage: benchmark
when: manual when: manual
@ -155,6 +163,17 @@ review_app:
- (ssh -t dokku@pleroma.online -- certs:add "$CI_ENVIRONMENT_SLUG" /home/dokku/server.crt /home/dokku/server.key) || true - (ssh -t dokku@pleroma.online -- certs:add "$CI_ENVIRONMENT_SLUG" /home/dokku/server.crt /home/dokku/server.key) || true
- git push -f dokku@pleroma.online:$CI_ENVIRONMENT_SLUG $CI_COMMIT_SHA:refs/heads/master - git push -f dokku@pleroma.online:$CI_ENVIRONMENT_SLUG $CI_COMMIT_SHA:refs/heads/master
spec-deploy:
stage: deploy
only:
- develop@pleroma/pleroma
image: alpine:latest
before_script:
- apk add curl
script:
- curl -X POST -F"token=$API_DOCS_PIPELINE_TRIGGER" -F'ref=master' -F"variables[BRANCH]=$CI_COMMIT_REF_NAME" https://git.pleroma.social/api/v4/projects/1130/trigger/pipeline
stop_review_app: stop_review_app:
image: alpine:3.9 image: alpine:3.9
stage: deploy stage: deploy

6
lib/mix/tasks/pleroma/openapi_spec.ex Normal file
View file

@ -0,0 +1,6 @@
defmodule Mix.Tasks.Pleroma.OpenapiSpec do
def run([path]) do
spec = Pleroma.Web.ApiSpec.spec(server_specific: false) |> Jason.encode!()
File.write(path, spec)
end
end

92
lib/pleroma/web/api_spec.ex
View file

@ -11,10 +11,10 @@ defmodule Pleroma.Web.ApiSpec do
@behaviour OpenApi @behaviour OpenApi
@impl OpenApi @impl OpenApi
def spec do def spec(opts \\ []) do
%OpenApi{ %OpenApi{
servers: servers:
if Phoenix.Endpoint.server?(:pleroma, Endpoint) do if opts[:server_specific] do
[ [
# Populate the Server info from a phoenix endpoint # Populate the Server info from a phoenix endpoint
OpenApiSpex.Server.from_endpoint(Endpoint) OpenApiSpex.Server.from_endpoint(Endpoint)
@ -23,9 +23,25 @@ def spec do
[] []
end, end,
info: %OpenApiSpex.Info{ info: %OpenApiSpex.Info{
title: "Pleroma", title: "Pleroma API",
description: Application.spec(:pleroma, :description) |> to_string(), description: """
version: Application.spec(:pleroma, :vsn) |> to_string() This is documentation for client Pleroma API. Most of the endpoints and entities come
from Mastodon API and have custom extensions on top.
While this document aims to be a complete guide to the client API Pleroma exposes,
the details are still being worked out. Some endpoints may have incomplete or poorly worded documentation.
You might want to check the following resources if something is not clear:
- [Legacy Pleroma-specific endpoint documentation](https://docs-develop.pleroma.social/backend/development/API/pleroma_api/)
- [Mastodon API documentation](https://docs.joinmastodon.org/client/intro/)
- [Differences in Mastodon API responses from vanilla Mastodon](https://docs-develop.pleroma.social/backend/development/API/differences_in_mastoapi_responses/)
Please report such occurences on our [issue tracker](https://git.pleroma.social/pleroma/pleroma/-/issues). Feel free to submit API questions or proposals there too!
""",
version: Application.spec(:pleroma, :vsn) |> to_string(),
extensions: %{
# Logo path should be picked so that the path exists both on Pleroma instances and on api.pleroma.social
"x-logo": %{"url" => "/static/logo.svg", "altText" => "Pleroma logo"}
}
}, },
# populate the paths from a phoenix router # populate the paths from a phoenix router
paths: OpenApiSpex.Paths.from_router(Router), paths: OpenApiSpex.Paths.from_router(Router),
@ -45,15 +61,73 @@ def spec do
authorizationUrl: "/oauth/authorize", authorizationUrl: "/oauth/authorize",
tokenUrl: "/oauth/token", tokenUrl: "/oauth/token",
scopes: %{ scopes: %{
"read" => "read", # TODO: Document granular scopes
"write" => "write", "read" => "Read everything",
"follow" => "follow", "write" => "Write everything",
"push" => "push" "follow" => "Manage relationships",
"push" => "Web Push API subscriptions"
} }
} }
} }
} }
} }
},
extensions: %{
# Redoc-specific extension, every time a new tag is added it should be reflected here,
# otherwise it won't be shown.
"x-tagGroups": [
%{
"name" => "Accounts",
"tags" => ["Account actions", "Retrieve account information", "Scrobbles"]
},
%{
"name" => "Administration",
"tags" => [
"Chat administration",
"Emoji packs",
"Frontend managment",
"Instance configuration",
"Instance documents",
"Invites",
"MediaProxy cache",
"OAuth application managment",
"Report managment",
"Relays",
"Status administration"
]
},
%{"name" => "Applications", "tags" => ["Applications", "Push subscriptions"]},
%{
"name" => "Current account",
"tags" => [
"Account credentials",
"Backups",
"Blocks and mutes",
"Data import",
"Domain blocks",
"Follow requests",
"Mascot",
"Markers",
"Notifications"
]
},
%{"name" => "Instance", "tags" => ["Custom emojis"]},
%{"name" => "Messaging", "tags" => ["Chats", "Conversations"]},
%{
"name" => "Statuses",
"tags" => [
"Emoji reactions",
"Lists",
"Polls",
"Timelines",
"Retrieve status information",
"Scheduled statuses",
"Search",
"Status actions"
]
},
%{"name" => "Miscellaneous", "tags" => ["Reports", "Suggestions"]}
]
} }
} }
# discover request/response schemas from path specs # discover request/response schemas from path specs

46
lib/pleroma/web/api_spec/operations/account_operation.ex
View file

@ -26,7 +26,7 @@ def open_api_operation(action) do
@spec create_operation() :: Operation.t() @spec create_operation() :: Operation.t()
def create_operation do def create_operation do
%Operation{ %Operation{
tags: ["accounts"], tags: ["Account credentials"],
summary: "Register an account", summary: "Register an account",
description: description:
"Creates a user and account records. Returns an account access token for the app that initiated the request. The app should save this token for later, and should wait for the user to confirm their account by clicking a link in their email inbox.", "Creates a user and account records. Returns an account access token for the app that initiated the request. The app should save this token for later, and should wait for the user to confirm their account by clicking a link in their email inbox.",
@ -43,7 +43,7 @@ def create_operation do
def verify_credentials_operation do def verify_credentials_operation do
%Operation{ %Operation{
tags: ["accounts"], tags: ["Account credentials"],
description: "Test to make sure that the user token works.", description: "Test to make sure that the user token works.",
summary: "Verify account credentials", summary: "Verify account credentials",
operationId: "AccountController.verify_credentials", operationId: "AccountController.verify_credentials",
@ -56,7 +56,7 @@ def verify_credentials_operation do
def update_credentials_operation do def update_credentials_operation do
%Operation{ %Operation{
tags: ["accounts"], tags: ["Account credentials"],
summary: "Update account credentials", summary: "Update account credentials",
description: "Update the user's display and preferences.", description: "Update the user's display and preferences.",
operationId: "AccountController.update_credentials", operationId: "AccountController.update_credentials",
@ -71,8 +71,8 @@ def update_credentials_operation do
def relationships_operation do def relationships_operation do
%Operation{ %Operation{
tags: ["accounts"], tags: ["Retrieve account information"],
summary: "Check relationships to other accounts", summary: "Relationship with current account",
operationId: "AccountController.relationships", operationId: "AccountController.relationships",
description: "Find out whether a given account is followed, blocked, muted, etc.", description: "Find out whether a given account is followed, blocked, muted, etc.",
security: [%{"oAuth" => ["read:follows"]}], security: [%{"oAuth" => ["read:follows"]}],
@ -95,7 +95,7 @@ def relationships_operation do
def show_operation do def show_operation do
%Operation{ %Operation{
tags: ["accounts"], tags: ["Retrieve account information"],
summary: "Account", summary: "Account",
operationId: "AccountController.show", operationId: "AccountController.show",
description: "View information about a profile.", description: "View information about a profile.",
@ -110,8 +110,8 @@ def show_operation do
def statuses_operation do def statuses_operation do
%Operation{ %Operation{
tags: ["accounts"],
summary: "Statuses", summary: "Statuses",
tags: ["Retrieve account information"],
operationId: "AccountController.statuses", operationId: "AccountController.statuses",
description: description:
"Statuses posted to the given account. Public (for public statuses only), or user token + `read:statuses` (for private statuses the user is authorized to see)", "Statuses posted to the given account. Public (for public statuses only), or user token + `read:statuses` (for private statuses the user is authorized to see)",
@ -157,7 +157,7 @@ def statuses_operation do
def followers_operation do def followers_operation do
%Operation{ %Operation{
tags: ["accounts"], tags: ["Retrieve account information"],
summary: "Followers", summary: "Followers",
operationId: "AccountController.followers", operationId: "AccountController.followers",
security: [%{"oAuth" => ["read:accounts"]}], security: [%{"oAuth" => ["read:accounts"]}],
@ -176,7 +176,7 @@ def followers_operation do
def following_operation do def following_operation do
%Operation{ %Operation{
tags: ["accounts"], tags: ["Retrieve account information"],
summary: "Following", summary: "Following",
operationId: "AccountController.following", operationId: "AccountController.following",
security: [%{"oAuth" => ["read:accounts"]}], security: [%{"oAuth" => ["read:accounts"]}],
@ -193,7 +193,7 @@ def following_operation do
def lists_operation do def lists_operation do
%Operation{ %Operation{
tags: ["accounts"], tags: ["Retrieve account information"],
summary: "Lists containing this account", summary: "Lists containing this account",
operationId: "AccountController.lists", operationId: "AccountController.lists",
security: [%{"oAuth" => ["read:lists"]}], security: [%{"oAuth" => ["read:lists"]}],
@ -205,7 +205,7 @@ def lists_operation do
def follow_operation do def follow_operation do
%Operation{ %Operation{
tags: ["accounts"], tags: ["Account actions"],
summary: "Follow", summary: "Follow",
operationId: "AccountController.follow", operationId: "AccountController.follow",
security: [%{"oAuth" => ["follow", "write:follows"]}], security: [%{"oAuth" => ["follow", "write:follows"]}],
@ -238,7 +238,7 @@ def follow_operation do
def unfollow_operation do def unfollow_operation do
%Operation{ %Operation{
tags: ["accounts"], tags: ["Account actions"],
summary: "Unfollow", summary: "Unfollow",
operationId: "AccountController.unfollow", operationId: "AccountController.unfollow",
security: [%{"oAuth" => ["follow", "write:follows"]}], security: [%{"oAuth" => ["follow", "write:follows"]}],
@ -254,7 +254,7 @@ def unfollow_operation do
def mute_operation do def mute_operation do
%Operation{ %Operation{
tags: ["accounts"], tags: ["Account actions"],
summary: "Mute", summary: "Mute",
operationId: "AccountController.mute", operationId: "AccountController.mute",
security: [%{"oAuth" => ["follow", "write:mutes"]}], security: [%{"oAuth" => ["follow", "write:mutes"]}],
@ -284,7 +284,7 @@ def mute_operation do
def unmute_operation do def unmute_operation do
%Operation{ %Operation{
tags: ["accounts"], tags: ["Account actions"],
summary: "Unmute", summary: "Unmute",
operationId: "AccountController.unmute", operationId: "AccountController.unmute",
security: [%{"oAuth" => ["follow", "write:mutes"]}], security: [%{"oAuth" => ["follow", "write:mutes"]}],
@ -298,7 +298,7 @@ def unmute_operation do
def block_operation do def block_operation do
%Operation{ %Operation{
tags: ["accounts"], tags: ["Account actions"],
summary: "Block", summary: "Block",
operationId: "AccountController.block", operationId: "AccountController.block",
security: [%{"oAuth" => ["follow", "write:blocks"]}], security: [%{"oAuth" => ["follow", "write:blocks"]}],
@ -313,7 +313,7 @@ def block_operation do
def unblock_operation do def unblock_operation do
%Operation{ %Operation{
tags: ["accounts"], tags: ["Account actions"],
summary: "Unblock", summary: "Unblock",
operationId: "AccountController.unblock", operationId: "AccountController.unblock",
security: [%{"oAuth" => ["follow", "write:blocks"]}], security: [%{"oAuth" => ["follow", "write:blocks"]}],
@ -327,7 +327,7 @@ def unblock_operation do
def follow_by_uri_operation do def follow_by_uri_operation do
%Operation{ %Operation{
tags: ["accounts"], tags: ["Account actions"],
summary: "Follow by URI", summary: "Follow by URI",
operationId: "AccountController.follows", operationId: "AccountController.follows",
security: [%{"oAuth" => ["follow", "write:follows"]}], security: [%{"oAuth" => ["follow", "write:follows"]}],
@ -342,8 +342,8 @@ def follow_by_uri_operation do
def mutes_operation do def mutes_operation do
%Operation{ %Operation{
tags: ["accounts"], tags: ["Blocks and mutes"],
summary: "Muted accounts", summary: "Retrieve list of mutes",
operationId: "AccountController.mutes", operationId: "AccountController.mutes",
description: "Accounts the user has muted.", description: "Accounts the user has muted.",
security: [%{"oAuth" => ["follow", "read:mutes"]}], security: [%{"oAuth" => ["follow", "read:mutes"]}],
@ -356,8 +356,8 @@ def mutes_operation do
def blocks_operation do def blocks_operation do
%Operation{ %Operation{
tags: ["accounts"], tags: ["Blocks and mutes"],
summary: "Blocked users", summary: "Retrieve list of blocks",
operationId: "AccountController.blocks", operationId: "AccountController.blocks",
description: "View your blocks. See also accounts/:id/{block,unblock}", description: "View your blocks. See also accounts/:id/{block,unblock}",
security: [%{"oAuth" => ["read:blocks"]}], security: [%{"oAuth" => ["read:blocks"]}],
@ -370,7 +370,7 @@ def blocks_operation do
def endorsements_operation do def endorsements_operation do
%Operation{ %Operation{
tags: ["accounts"], tags: ["Retrieve account information"],
summary: "Endorsements", summary: "Endorsements",
operationId: "AccountController.endorsements", operationId: "AccountController.endorsements",
description: "Not implemented", description: "Not implemented",
@ -383,7 +383,7 @@ def endorsements_operation do
def identity_proofs_operation do def identity_proofs_operation do
%Operation{ %Operation{
tags: ["accounts"], tags: ["Retrieve account information"],
summary: "Identity proofs", summary: "Identity proofs",
operationId: "AccountController.identity_proofs", operationId: "AccountController.identity_proofs",
# Validators complains about unused path params otherwise # Validators complains about unused path params otherwise

8
lib/pleroma/web/api_spec/operations/admin/chat_operation.ex
View file

@ -16,7 +16,7 @@ def open_api_operation(action) do
def delete_message_operation do def delete_message_operation do
%Operation{ %Operation{
tags: ["admin", "chat"], tags: ["Chat administration"],
summary: "Delete an individual chat message", summary: "Delete an individual chat message",
operationId: "AdminAPI.ChatController.delete_message", operationId: "AdminAPI.ChatController.delete_message",
parameters: [ parameters: [
@ -41,8 +41,8 @@ def delete_message_operation do
def messages_operation do def messages_operation do
%Operation{ %Operation{
tags: ["admin", "chat"], tags: ["Chat administration"],
summary: "Get the most recent messages of the chat", summary: "Get chat's messages",
operationId: "AdminAPI.ChatController.messages", operationId: "AdminAPI.ChatController.messages",
parameters: parameters:
[Operation.parameter(:id, :path, :string, "The ID of the Chat")] ++ [Operation.parameter(:id, :path, :string, "The ID of the Chat")] ++
@ -65,7 +65,7 @@ def messages_operation do
def show_operation do def show_operation do
%Operation{ %Operation{
tags: ["chat"], tags: ["Chat administration"],
summary: "Create a chat", summary: "Create a chat",
operationId: "AdminAPI.ChatController.show", operationId: "AdminAPI.ChatController.show",
parameters: [ parameters: [

12
lib/pleroma/web/api_spec/operations/admin/config_operation.ex
View file

@ -16,8 +16,8 @@ def open_api_operation(action) do
def show_operation do def show_operation do
%Operation{ %Operation{
tags: ["Admin", "Config"], tags: ["Instance configuration"],
summary: "Get list of merged default settings with saved in database", summary: "Retrieve instance configuration",
operationId: "AdminAPI.ConfigController.show", operationId: "AdminAPI.ConfigController.show",
parameters: [ parameters: [
Operation.parameter( Operation.parameter(
@ -38,8 +38,8 @@ def show_operation do
def update_operation do def update_operation do
%Operation{ %Operation{
tags: ["Admin", "Config"], tags: ["Instance configuration"],
summary: "Update config settings", summary: "Update instance configuration",
operationId: "AdminAPI.ConfigController.update", operationId: "AdminAPI.ConfigController.update",
security: [%{"oAuth" => ["write"]}], security: [%{"oAuth" => ["write"]}],
parameters: admin_api_params(), parameters: admin_api_params(),
@ -71,8 +71,8 @@ def update_operation do
def descriptions_operation do def descriptions_operation do
%Operation{ %Operation{
tags: ["Admin", "Config"], tags: ["Instance configuration"],
summary: "Get JSON with config descriptions.", summary: "Retrieve config description",
operationId: "AdminAPI.ConfigController.descriptions", operationId: "AdminAPI.ConfigController.descriptions",
security: [%{"oAuth" => ["read"]}], security: [%{"oAuth" => ["read"]}],
parameters: admin_api_params(), parameters: admin_api_params(),

6
lib/pleroma/web/api_spec/operations/admin/frontend_operation.ex
View file

@ -16,8 +16,8 @@ def open_api_operation(action) do
def index_operation do def index_operation do
%Operation{ %Operation{
tags: ["Admin", "Reports"], tags: ["Frontend managment"],
summary: "Get a list of available frontends", summary: "Retrieve a list of available frontends",
operationId: "AdminAPI.FrontendController.index", operationId: "AdminAPI.FrontendController.index",
security: [%{"oAuth" => ["read"]}], security: [%{"oAuth" => ["read"]}],
responses: %{ responses: %{
@ -29,7 +29,7 @@ def index_operation do
def install_operation do def install_operation do
%Operation{ %Operation{
tags: ["Admin", "Reports"], tags: ["Frontend managment"],
summary: "Install a frontend", summary: "Install a frontend",
operationId: "AdminAPI.FrontendController.install", operationId: "AdminAPI.FrontendController.install",
security: [%{"oAuth" => ["read"]}], security: [%{"oAuth" => ["read"]}],

12
lib/pleroma/web/api_spec/operations/admin/instance_document_operation.ex
View file

@ -15,8 +15,8 @@ def open_api_operation(action) do
def show_operation do def show_operation do
%Operation{ %Operation{
tags: ["Admin", "InstanceDocument"], tags: ["Instance documents"],
summary: "Get the instance document", summary: "Retrieve an instance document",
operationId: "AdminAPI.InstanceDocumentController.show", operationId: "AdminAPI.InstanceDocumentController.show",
security: [%{"oAuth" => ["read"]}], security: [%{"oAuth" => ["read"]}],
parameters: [ parameters: [
@ -36,8 +36,8 @@ def show_operation do
def update_operation do def update_operation do
%Operation{ %Operation{
tags: ["Admin", "InstanceDocument"], tags: ["Instance documents"],
summary: "Update the instance document", summary: "Update an instance document",
operationId: "AdminAPI.InstanceDocumentController.update", operationId: "AdminAPI.InstanceDocumentController.update",
security: [%{"oAuth" => ["write"]}], security: [%{"oAuth" => ["write"]}],
requestBody: Helpers.request_body("Parameters", update_request()), requestBody: Helpers.request_body("Parameters", update_request()),
@ -74,8 +74,8 @@ defp update_request do
def delete_operation do def delete_operation do
%Operation{ %Operation{
tags: ["Admin", "InstanceDocument"], tags: ["Instance documents"],
summary: "Get the instance document", summary: "Delete an instance document",
operationId: "AdminAPI.InstanceDocumentController.delete", operationId: "AdminAPI.InstanceDocumentController.delete",
security: [%{"oAuth" => ["write"]}], security: [%{"oAuth" => ["write"]}],
parameters: [ parameters: [

8
lib/pleroma/web/api_spec/operations/admin/invite_operation.ex
View file

@ -16,7 +16,7 @@ def open_api_operation(action) do
def index_operation do def index_operation do
%Operation{ %Operation{
tags: ["Admin", "Invites"], tags: ["Invites"],
summary: "Get a list of generated invites", summary: "Get a list of generated invites",
operationId: "AdminAPI.InviteController.index", operationId: "AdminAPI.InviteController.index",
security: [%{"oAuth" => ["read:invites"]}], security: [%{"oAuth" => ["read:invites"]}],
@ -48,7 +48,7 @@ def index_operation do
def create_operation do def create_operation do
%Operation{ %Operation{
tags: ["Admin", "Invites"], tags: ["Invites"],
summary: "Create an account registration invite token", summary: "Create an account registration invite token",
operationId: "AdminAPI.InviteController.create", operationId: "AdminAPI.InviteController.create",
security: [%{"oAuth" => ["write:invites"]}], security: [%{"oAuth" => ["write:invites"]}],
@ -69,7 +69,7 @@ def create_operation do
def revoke_operation do def revoke_operation do
%Operation{ %Operation{
tags: ["Admin", "Invites"], tags: ["Invites"],
summary: "Revoke invite by token", summary: "Revoke invite by token",
operationId: "AdminAPI.InviteController.revoke", operationId: "AdminAPI.InviteController.revoke",
security: [%{"oAuth" => ["write:invites"]}], security: [%{"oAuth" => ["write:invites"]}],
@ -96,7 +96,7 @@ def revoke_operation do
def email_operation do def email_operation do
%Operation{ %Operation{
tags: ["Admin", "Invites"], tags: ["Invites"],
summary: "Sends registration invite via email", summary: "Sends registration invite via email",
operationId: "AdminAPI.InviteController.email", operationId: "AdminAPI.InviteController.email",
security: [%{"oAuth" => ["write:invites"]}], security: [%{"oAuth" => ["write:invites"]}],

14
lib/pleroma/web/api_spec/operations/admin/media_proxy_cache_operation.ex
View file

@ -16,8 +16,8 @@ def open_api_operation(action) do
def index_operation do def index_operation do
%Operation{ %Operation{
tags: ["Admin", "MediaProxyCache"], tags: ["MediaProxy cache"],
summary: "Fetch a paginated list of all banned MediaProxy URLs in Cachex", summary: "Retrieve a list of banned MediaProxy URLs",
operationId: "AdminAPI.MediaProxyCacheController.index", operationId: "AdminAPI.MediaProxyCacheController.index",
security: [%{"oAuth" => ["read:media_proxy_caches"]}], security: [%{"oAuth" => ["read:media_proxy_caches"]}],
parameters: [ parameters: [
@ -44,7 +44,7 @@ def index_operation do
responses: %{ responses: %{
200 => 200 =>
Operation.response( Operation.response(
"Array of banned MediaProxy URLs in Cachex", "Array of MediaProxy URLs",
"application/json", "application/json",
%Schema{ %Schema{
type: :object, type: :object,
@ -68,8 +68,8 @@ def index_operation do
def delete_operation do def delete_operation do
%Operation{ %Operation{
tags: ["Admin", "MediaProxyCache"], tags: ["MediaProxy cache"],
summary: "Remove a banned MediaProxy URL from Cachex", summary: "Remove a banned MediaProxy URL",
operationId: "AdminAPI.MediaProxyCacheController.delete", operationId: "AdminAPI.MediaProxyCacheController.delete",
security: [%{"oAuth" => ["write:media_proxy_caches"]}], security: [%{"oAuth" => ["write:media_proxy_caches"]}],
parameters: admin_api_params(), parameters: admin_api_params(),
@ -94,8 +94,8 @@ def delete_operation do
def purge_operation do def purge_operation do
%Operation{ %Operation{
tags: ["Admin", "MediaProxyCache"], tags: ["MediaProxy cache"],
summary: "Purge and optionally ban a MediaProxy URL", summary: "Purge a URL from MediaProxy cache and optionally ban it",
operationId: "AdminAPI.MediaProxyCacheController.purge", operationId: "AdminAPI.MediaProxyCacheController.purge",
security: [%{"oAuth" => ["write:media_proxy_caches"]}], security: [%{"oAuth" => ["write:media_proxy_caches"]}],
parameters: admin_api_params(), parameters: admin_api_params(),

16
lib/pleroma/web/api_spec/operations/admin/o_auth_app_operation.ex
View file

@ -16,8 +16,8 @@ def open_api_operation(action) do
def index_operation do def index_operation do
%Operation{ %Operation{
summary: "List OAuth apps", summary: "Retrieve a list of OAuth applications",
tags: ["Admin", "oAuth Apps"], tags: ["OAuth application managment"],
operationId: "AdminAPI.OAuthAppController.index", operationId: "AdminAPI.OAuthAppController.index",
security: [%{"oAuth" => ["write"]}], security: [%{"oAuth" => ["write"]}],
parameters: [ parameters: [
@ -69,8 +69,8 @@ def index_operation do
def create_operation do def create_operation do
%Operation{ %Operation{
tags: ["Admin", "oAuth Apps"], tags: ["OAuth application managment"],
summary: "Create OAuth App", summary: "Create an OAuth application",
operationId: "AdminAPI.OAuthAppController.create", operationId: "AdminAPI.OAuthAppController.create",
requestBody: request_body("Parameters", create_request()), requestBody: request_body("Parameters", create_request()),
parameters: admin_api_params(), parameters: admin_api_params(),
@ -84,8 +84,8 @@ def create_operation do
def update_operation do def update_operation do
%Operation{ %Operation{
tags: ["Admin", "oAuth Apps"], tags: ["OAuth application managment"],
summary: "Update OAuth App", summary: "Update OAuth application",
operationId: "AdminAPI.OAuthAppController.update", operationId: "AdminAPI.OAuthAppController.update",
parameters: [id_param() | admin_api_params()], parameters: [id_param() | admin_api_params()],
security: [%{"oAuth" => ["write"]}], security: [%{"oAuth" => ["write"]}],
@ -102,8 +102,8 @@ def update_operation do
def delete_operation do def delete_operation do
%Operation{ %Operation{
tags: ["Admin", "oAuth Apps"], tags: ["OAuth application managment"],
summary: "Delete OAuth App", summary: "Delete OAuth application",
operationId: "AdminAPI.OAuthAppController.delete", operationId: "AdminAPI.OAuthAppController.delete",
parameters: [id_param() | admin_api_params()], parameters: [id_param() | admin_api_params()],
security: [%{"oAuth" => ["write"]}], security: [%{"oAuth" => ["write"]}],

12
lib/pleroma/web/api_spec/operations/admin/relay_operation.ex
View file

@ -15,8 +15,8 @@ def open_api_operation(action) do
def index_operation do def index_operation do
%Operation{ %Operation{
tags: ["Admin", "Relays"], tags: ["Relays"],
summary: "List Relays", summary: "Retrieve a list of relays",
operationId: "AdminAPI.RelayController.index", operationId: "AdminAPI.RelayController.index",
security: [%{"oAuth" => ["read"]}], security: [%{"oAuth" => ["read"]}],
parameters: admin_api_params(), parameters: admin_api_params(),
@ -37,8 +37,8 @@ def index_operation do
def follow_operation do def follow_operation do
%Operation{ %Operation{
tags: ["Admin", "Relays"], tags: ["Relays"],
summary: "Follow a Relay", summary: "Follow a relay",
operationId: "AdminAPI.RelayController.follow", operationId: "AdminAPI.RelayController.follow",
security: [%{"oAuth" => ["write:follows"]}], security: [%{"oAuth" => ["write:follows"]}],
parameters: admin_api_params(), parameters: admin_api_params(),
@ -51,8 +51,8 @@ def follow_operation do
def unfollow_operation do def unfollow_operation do
%Operation{ %Operation{
tags: ["Admin", "Relays"], tags: ["Relays"],
summary: "Unfollow a Relay", summary: "Unfollow a relay",
operationId: "AdminAPI.RelayController.unfollow", operationId: "AdminAPI.RelayController.unfollow",
security: [%{"oAuth" => ["write:follows"]}], security: [%{"oAuth" => ["write:follows"]}],
parameters: admin_api_params(), parameters: admin_api_params(),

20
lib/pleroma/web/api_spec/operations/admin/report_operation.ex
View file

@ -19,8 +19,8 @@ def open_api_operation(action) do
def index_operation do def index_operation do
%Operation{ %Operation{
tags: ["Admin", "Reports"], tags: ["Report managment"],
summary: "Get a list of reports", summary: "Retrieve a list of reports",
operationId: "AdminAPI.ReportController.index", operationId: "AdminAPI.ReportController.index",
security: [%{"oAuth" => ["read:reports"]}], security: [%{"oAuth" => ["read:reports"]}],
parameters: [ parameters: [
@ -69,8 +69,8 @@ def index_operation do
def show_operation do def show_operation do
%Operation{ %Operation{
tags: ["Admin", "Reports"], tags: ["Report managment"],
summary: "Get an individual report", summary: "Retrieve a report",
operationId: "AdminAPI.ReportController.show", operationId: "AdminAPI.ReportController.show",
parameters: [id_param() | admin_api_params()], parameters: [id_param() | admin_api_params()],
security: [%{"oAuth" => ["read:reports"]}], security: [%{"oAuth" => ["read:reports"]}],
@ -83,8 +83,8 @@ def show_operation do
def update_operation do def update_operation do
%Operation{ %Operation{
tags: ["Admin", "Reports"], tags: ["Report managment"],
summary: "Change the state of one or multiple reports", summary: "Change state of specified reports",
operationId: "AdminAPI.ReportController.update", operationId: "AdminAPI.ReportController.update",
security: [%{"oAuth" => ["write:reports"]}], security: [%{"oAuth" => ["write:reports"]}],
parameters: admin_api_params(), parameters: admin_api_params(),
@ -99,8 +99,8 @@ def update_operation do
def notes_create_operation do def notes_create_operation do
%Operation{ %Operation{
tags: ["Admin", "Reports"], tags: ["Report managment"],
summary: "Create report note", summary: "Add a note to the report",
operationId: "AdminAPI.ReportController.notes_create", operationId: "AdminAPI.ReportController.notes_create",
parameters: [id_param() | admin_api_params()], parameters: [id_param() | admin_api_params()],
requestBody: requestBody:
@ -120,8 +120,8 @@ def notes_create_operation do
def notes_delete_operation do def notes_delete_operation do
%Operation{ %Operation{
tags: ["Admin", "Reports"], tags: ["Report managment"],
summary: "Delete report note", summary: "Delete note attached to the report",
operationId: "AdminAPI.ReportController.notes_delete", operationId: "AdminAPI.ReportController.notes_delete",
parameters: [ parameters: [
Operation.parameter(:report_id, :path, :string, "Report ID"), Operation.parameter(:report_id, :path, :string, "Report ID"),

15
lib/pleroma/web/api_spec/operations/admin/status_operation.ex
View file

@ -21,8 +21,9 @@ def open_api_operation(action) do
def index_operation do def index_operation do
%Operation{ %Operation{
tags: ["Admin", "Statuses"], tags: ["Status administration"],
operationId: "AdminAPI.StatusController.index", operationId: "AdminAPI.StatusController.index",
summary: "Get all statuses",
security: [%{"oAuth" => ["read:statuses"]}], security: [%{"oAuth" => ["read:statuses"]}],
parameters: [ parameters: [
Operation.parameter( Operation.parameter(
@ -69,8 +70,8 @@ def index_operation do
def show_operation do def show_operation do
%Operation{ %Operation{
tags: ["Admin", "Statuses"], tags: ["Status adminitration)"],
summary: "Show Status", summary: "Get status",
operationId: "AdminAPI.StatusController.show", operationId: "AdminAPI.StatusController.show",
parameters: [id_param() | admin_api_params()], parameters: [id_param() | admin_api_params()],
security: [%{"oAuth" => ["read:statuses"]}], security: [%{"oAuth" => ["read:statuses"]}],
@ -83,8 +84,8 @@ def show_operation do
def update_operation do def update_operation do
%Operation{ %Operation{
tags: ["Admin", "Statuses"], tags: ["Status adminitration)"],
summary: "Change the scope of an individual reported status", summary: "Change the scope of a status",
operationId: "AdminAPI.StatusController.update", operationId: "AdminAPI.StatusController.update",
parameters: [id_param() | admin_api_params()], parameters: [id_param() | admin_api_params()],
security: [%{"oAuth" => ["write:statuses"]}], security: [%{"oAuth" => ["write:statuses"]}],
@ -98,8 +99,8 @@ def update_operation do
def delete_operation do def delete_operation do
%Operation{ %Operation{
tags: ["Admin", "Statuses"], tags: ["Status adminitration)"],
summary: "Delete an individual reported status", summary: "Delete status",
operationId: "AdminAPI.StatusController.delete", operationId: "AdminAPI.StatusController.delete",
parameters: [id_param() | admin_api_params()], parameters: [id_param() | admin_api_params()],
security: [%{"oAuth" => ["write:statuses"]}], security: [%{"oAuth" => ["write:statuses"]}],

6
lib/pleroma/web/api_spec/operations/app_operation.ex
View file

@ -16,7 +16,7 @@ def open_api_operation(action) do
@spec create_operation() :: Operation.t() @spec create_operation() :: Operation.t()
def create_operation do def create_operation do
%Operation{ %Operation{
tags: ["apps"], tags: ["Applications"],
summary: "Create an application", summary: "Create an application",
description: "Create a new application to obtain OAuth2 credentials", description: "Create a new application to obtain OAuth2 credentials",
operationId: "AppController.create", operationId: "AppController.create",
@ -45,8 +45,8 @@ def create_operation do
def verify_credentials_operation do def verify_credentials_operation do
%Operation{ %Operation{
tags: ["apps"], tags: ["Applications"],
summary: "Verify your app works", summary: "Verify the application works",
description: "Confirm that the app's OAuth2 credentials work.", description: "Confirm that the app's OAuth2 credentials work.",
operationId: "AppController.verify_credentials", operationId: "AppController.verify_credentials",
security: [%{"oAuth" => ["read"]}], security: [%{"oAuth" => ["read"]}],

26
lib/pleroma/web/api_spec/operations/chat_operation.ex
View file

@ -20,7 +20,7 @@ def open_api_operation(action) do
def mark_as_read_operation do def mark_as_read_operation do
%Operation{ %Operation{
tags: ["chat"], tags: ["Chats"],
summary: "Mark all messages in the chat as read", summary: "Mark all messages in the chat as read",
operationId: "ChatController.mark_as_read", operationId: "ChatController.mark_as_read",
parameters: [Operation.parameter(:id, :path, :string, "The ID of the Chat")], parameters: [Operation.parameter(:id, :path, :string, "The ID of the Chat")],
@ -43,8 +43,8 @@ def mark_as_read_operation do
def mark_message_as_read_operation do def mark_message_as_read_operation do
%Operation{ %Operation{
tags: ["chat"], tags: ["Chats"],
summary: "Mark one message in the chat as read", summary: "Mark a message as read",
operationId: "ChatController.mark_message_as_read", operationId: "ChatController.mark_message_as_read",
parameters: [ parameters: [
Operation.parameter(:id, :path, :string, "The ID of the Chat"), Operation.parameter(:id, :path, :string, "The ID of the Chat"),
@ -68,8 +68,8 @@ def mark_message_as_read_operation do
def show_operation do def show_operation do
%Operation{ %Operation{
tags: ["chat"], tags: ["Chats"],
summary: "Create a chat", summary: "Retrieve a chat",
operationId: "ChatController.show", operationId: "ChatController.show",
parameters: [ parameters: [
Operation.parameter( Operation.parameter(
@ -99,7 +99,7 @@ def show_operation do
def create_operation do def create_operation do
%Operation{ %Operation{
tags: ["chat"], tags: ["Chats"],
summary: "Create a chat", summary: "Create a chat",
operationId: "ChatController.create", operationId: "ChatController.create",
parameters: [ parameters: [
@ -130,8 +130,8 @@ def create_operation do
def index_operation do def index_operation do
%Operation{ %Operation{
tags: ["chat"], tags: ["Chats"],
summary: "Get a list of chats that you participated in", summary: "Retrieve list of chats",
operationId: "ChatController.index", operationId: "ChatController.index",
parameters: [ parameters: [
Operation.parameter(:with_muted, :query, BooleanLike, "Include chats from muted users") Operation.parameter(:with_muted, :query, BooleanLike, "Include chats from muted users")
@ -150,8 +150,8 @@ def index_operation do
def messages_operation do def messages_operation do
%Operation{ %Operation{
tags: ["chat"], tags: ["Chats"],
summary: "Get the most recent messages of the chat", summary: "Retrieve chat's messages",
operationId: "ChatController.messages", operationId: "ChatController.messages",
parameters: parameters:
[Operation.parameter(:id, :path, :string, "The ID of the Chat")] ++ [Operation.parameter(:id, :path, :string, "The ID of the Chat")] ++
@ -175,7 +175,7 @@ def messages_operation do
def post_chat_message_operation do def post_chat_message_operation do
%Operation{ %Operation{
tags: ["chat"], tags: ["Chats"],
summary: "Post a message to the chat", summary: "Post a message to the chat",
operationId: "ChatController.post_chat_message", operationId: "ChatController.post_chat_message",
parameters: [ parameters: [
@ -202,8 +202,8 @@ def post_chat_message_operation do
def delete_message_operation do def delete_message_operation do
%Operation{ %Operation{
tags: ["chat"], tags: ["Chats"],
summary: "delete_message", summary: "Delete message",
operationId: "ChatController.delete_message", operationId: "ChatController.delete_message",
parameters: [ parameters: [
Operation.parameter(:id, :path, :string, "The ID of the Chat"), Operation.parameter(:id, :path, :string, "The ID of the Chat"),

4
lib/pleroma/web/api_spec/operations/conversation_operation.ex
View file

@ -18,7 +18,7 @@ def open_api_operation(action) do
def index_operation do def index_operation do
%Operation{ %Operation{
tags: ["Conversations"], tags: ["Conversations"],
summary: "Show conversation", summary: "List of conversations",
security: [%{"oAuth" => ["read:statuses"]}], security: [%{"oAuth" => ["read:statuses"]}],
operationId: "ConversationController.index", operationId: "ConversationController.index",
parameters: [ parameters: [
@ -44,7 +44,7 @@ def index_operation do
def mark_as_read_operation do def mark_as_read_operation do
%Operation{ %Operation{
tags: ["Conversations"], tags: ["Conversations"],
summary: "Mark as read", summary: "Mark conversation as read",
operationId: "ConversationController.mark_as_read", operationId: "ConversationController.mark_as_read",
parameters: [ parameters: [
Operation.parameter(:id, :path, :string, "Conversation ID", Operation.parameter(:id, :path, :string, "Conversation ID",

4
lib/pleroma/web/api_spec/operations/custom_emoji_operation.ex
View file

@ -14,8 +14,8 @@ def open_api_operation(action) do
def index_operation do def index_operation do
%Operation{ %Operation{
tags: ["custom_emojis"], tags: ["Custom emojis"],
summary: "List custom custom emojis", summary: "Retrieve a list of custom emojis",
description: "Returns custom emojis that are available on the server.", description: "Returns custom emojis that are available on the server.",
operationId: "CustomEmojiController.index", operationId: "CustomEmojiController.index",
responses: %{ responses: %{

9
lib/pleroma/web/api_spec/operations/domain_block_operation.ex
View file

@ -14,9 +14,8 @@ def open_api_operation(action) do
def index_operation do def index_operation do
%Operation{ %Operation{
tags: ["domain_blocks"], tags: ["Domain blocks"],
summary: "Fetch domain blocks", summary: "Retrieve a list of blocked domains",
description: "View domains the user has blocked.",
security: [%{"oAuth" => ["follow", "read:blocks"]}], security: [%{"oAuth" => ["follow", "read:blocks"]}],
operationId: "DomainBlockController.index", operationId: "DomainBlockController.index",
responses: %{ responses: %{
@ -34,7 +33,7 @@ def index_operation do
# Supporting domain query parameter is deprecated in Mastodon API # Supporting domain query parameter is deprecated in Mastodon API
def create_operation do def create_operation do
%Operation{ %Operation{
tags: ["domain_blocks"], tags: ["Domain blocks"],
summary: "Block a domain", summary: "Block a domain",
description: """ description: """
Block a domain to: Block a domain to:
@ -55,7 +54,7 @@ def create_operation do
# Supporting domain query parameter is deprecated in Mastodon API # Supporting domain query parameter is deprecated in Mastodon API
def delete_operation do def delete_operation do
%Operation{ %Operation{
tags: ["domain_blocks"], tags: ["Domain blocks"],
summary: "Unblock a domain", summary: "Unblock a domain",
description: "Remove a domain block, if it exists in the user's array of blocked domains.", description: "Remove a domain block, if it exists in the user's array of blocked domains.",
operationId: "DomainBlockController.delete", operationId: "DomainBlockController.delete",

8
lib/pleroma/web/api_spec/operations/emoji_reaction_operation.ex
View file

@ -17,7 +17,7 @@ def open_api_operation(action) do
def index_operation do def index_operation do
%Operation{ %Operation{
tags: ["Emoji Reactions"], tags: ["Emoji reactions"],
summary: summary:
"Get an object of emoji to account mappings with accounts that reacted to the post", "Get an object of emoji to account mappings with accounts that reacted to the post",
parameters: [ parameters: [
@ -42,7 +42,7 @@ def index_operation do
def create_operation do def create_operation do
%Operation{ %Operation{
tags: ["Emoji Reactions"], tags: ["Emoji reactions"],
summary: "React to a post with a unicode emoji", summary: "React to a post with a unicode emoji",
parameters: [ parameters: [
Operation.parameter(:id, :path, FlakeID, "Status ID", required: true), Operation.parameter(:id, :path, FlakeID, "Status ID", required: true),
@ -61,7 +61,7 @@ def create_operation do
def delete_operation do def delete_operation do
%Operation{ %Operation{
tags: ["Emoji Reactions"], tags: ["Emoji reactions"],
summary: "Remove a reaction to a post with a unicode emoji", summary: "Remove a reaction to a post with a unicode emoji",
parameters: [ parameters: [
Operation.parameter(:id, :path, FlakeID, "Status ID", required: true), Operation.parameter(:id, :path, FlakeID, "Status ID", required: true),
@ -78,7 +78,7 @@ def delete_operation do
end end
defp array_of_reactions_response do defp array_of_reactions_response do
Operation.response("Array of Emoji Reactions", "application/json", %Schema{ Operation.response("Array of Emoji reactions", "application/json", %Schema{
type: :array, type: :array,
items: emoji_reaction(), items: emoji_reaction(),
example: [emoji_reaction().example] example: [emoji_reaction().example]

14
lib/pleroma/web/api_spec/operations/filter_operation.ex
View file

@ -15,8 +15,8 @@ def open_api_operation(action) do
def index_operation do def index_operation do
%Operation{ %Operation{
tags: ["apps"], tags: ["Filters"],
summary: "View all filters", summary: "All filters",
operationId: "FilterController.index", operationId: "FilterController.index",
security: [%{"oAuth" => ["read:filters"]}], security: [%{"oAuth" => ["read:filters"]}],
responses: %{ responses: %{
@ -27,7 +27,7 @@ def index_operation do
def create_operation do def create_operation do
%Operation{ %Operation{
tags: ["apps"], tags: ["Filters"],
summary: "Create a filter", summary: "Create a filter",
operationId: "FilterController.create", operationId: "FilterController.create",
requestBody: Helpers.request_body("Parameters", create_request(), required: true), requestBody: Helpers.request_body("Parameters", create_request(), required: true),
@ -38,8 +38,8 @@ def create_operation do
def show_operation do def show_operation do
%Operation{ %Operation{
tags: ["apps"], tags: ["Filters"],
summary: "View all filters", summary: "Filter",
parameters: [id_param()], parameters: [id_param()],
operationId: "FilterController.show", operationId: "FilterController.show",
security: [%{"oAuth" => ["read:filters"]}], security: [%{"oAuth" => ["read:filters"]}],
@ -51,7 +51,7 @@ def show_operation do
def update_operation do def update_operation do
%Operation{ %Operation{
tags: ["apps"], tags: ["Filters"],
summary: "Update a filter", summary: "Update a filter",
parameters: [id_param()], parameters: [id_param()],
operationId: "FilterController.update", operationId: "FilterController.update",
@ -65,7 +65,7 @@ def update_operation do
def delete_operation do def delete_operation do
%Operation{ %Operation{
tags: ["apps"], tags: ["Filters"],
summary: "Remove a filter", summary: "Remove a filter",
parameters: [id_param()], parameters: [id_param()],
operationId: "FilterController.delete", operationId: "FilterController.delete",

12
lib/pleroma/web/api_spec/operations/follow_request_operation.ex
View file

@ -15,8 +15,8 @@ def open_api_operation(action) do
def index_operation do def index_operation do
%Operation{ %Operation{
tags: ["Follow Requests"], tags: ["Follow requests"],
summary: "Pending Follows", summary: "Retrieve follow requests",
security: [%{"oAuth" => ["read:follows", "follow"]}], security: [%{"oAuth" => ["read:follows", "follow"]}],
operationId: "FollowRequestController.index", operationId: "FollowRequestController.index",
responses: %{ responses: %{
@ -32,8 +32,8 @@ def index_operation do
def authorize_operation do def authorize_operation do
%Operation{ %Operation{
tags: ["Follow Requests"], tags: ["Follow requests"],
summary: "Accept Follow", summary: "Accept follow request",
operationId: "FollowRequestController.authorize", operationId: "FollowRequestController.authorize",
parameters: [id_param()], parameters: [id_param()],
security: [%{"oAuth" => ["follow", "write:follows"]}], security: [%{"oAuth" => ["follow", "write:follows"]}],
@ -45,8 +45,8 @@ def authorize_operation do
def reject_operation do def reject_operation do
%Operation{ %Operation{
tags: ["Follow Requests"], tags: ["Follow requests"],
summary: "Reject Follow", summary: "Reject follow request",
operationId: "FollowRequestController.reject", operationId: "FollowRequestController.reject",
parameters: [id_param()], parameters: [id_param()],
security: [%{"oAuth" => ["follow", "write:follows"]}], security: [%{"oAuth" => ["follow", "write:follows"]}],

4
lib/pleroma/web/api_spec/operations/instance_operation.ex
View file

@ -14,7 +14,7 @@ def open_api_operation(action) do
def show_operation do def show_operation do
%Operation{ %Operation{
tags: ["Instance"], tags: ["Instance"],
summary: "Fetch instance", summary: "Retrieve instance information",
description: "Information about the server", description: "Information about the server",
operationId: "InstanceController.show", operationId: "InstanceController.show",
responses: %{ responses: %{
@ -26,7 +26,7 @@ def show_operation do
def peers_operation do def peers_operation do
%Operation{ %Operation{
tags: ["Instance"], tags: ["Instance"],
summary: "List of known hosts", summary: "Retrieve list of known instances",
operationId: "InstanceController.peers", operationId: "InstanceController.peers",
responses: %{ responses: %{
200 => Operation.response("Array of domains", "application/json", array_of_domains()) 200 => Operation.response("Array of domains", "application/json", array_of_domains())

8
lib/pleroma/web/api_spec/operations/list_operation.ex
View file

@ -20,7 +20,7 @@ def open_api_operation(action) do
def index_operation do def index_operation do
%Operation{ %Operation{
tags: ["Lists"], tags: ["Lists"],
summary: "Show user's lists", summary: "Retrieve a list of lists",
description: "Fetch all lists that the user owns", description: "Fetch all lists that the user owns",
security: [%{"oAuth" => ["read:lists"]}], security: [%{"oAuth" => ["read:lists"]}],
operationId: "ListController.index", operationId: "ListController.index",
@ -33,7 +33,7 @@ def index_operation do
def create_operation do def create_operation do
%Operation{ %Operation{
tags: ["Lists"], tags: ["Lists"],
summary: "Create a list", summary: "Create a list",
description: "Fetch the list with the given ID. Used for verifying the title of a list.", description: "Fetch the list with the given ID. Used for verifying the title of a list.",
operationId: "ListController.create", operationId: "ListController.create",
requestBody: create_update_request(), requestBody: create_update_request(),
@ -49,7 +49,7 @@ def create_operation do
def show_operation do def show_operation do
%Operation{ %Operation{
tags: ["Lists"], tags: ["Lists"],
summary: "Show a single list", summary: "Retrieve a list",
description: "Fetch the list with the given ID. Used for verifying the title of a list.", description: "Fetch the list with the given ID. Used for verifying the title of a list.",
operationId: "ListController.show", operationId: "ListController.show",
parameters: [id_param()], parameters: [id_param()],
@ -93,7 +93,7 @@ def delete_operation do
def list_accounts_operation do def list_accounts_operation do
%Operation{ %Operation{
tags: ["Lists"], tags: ["Lists"],
summary: "View accounts in list", summary: "Retrieve accounts in list",
operationId: "ListController.list_accounts", operationId: "ListController.list_accounts",
parameters: [id_param()], parameters: [id_param()],
security: [%{"oAuth" => ["read:lists"]}], security: [%{"oAuth" => ["read:lists"]}],

14
lib/pleroma/web/api_spec/operations/media_operation.ex
View file

@ -16,7 +16,7 @@ def open_api_operation(action) do
def create_operation do def create_operation do
%Operation{ %Operation{
tags: ["media"], tags: ["Media attachments"],
summary: "Upload media as attachment", summary: "Upload media as attachment",
description: "Creates an attachment to be used with a new status.", description: "Creates an attachment to be used with a new status.",
operationId: "MediaController.create", operationId: "MediaController.create",
@ -56,8 +56,8 @@ defp create_request do
def update_operation do def update_operation do
%Operation{ %Operation{
tags: ["media"], tags: ["Media attachments"],
summary: "Upload media as attachment", summary: "Update attachment",
description: "Creates an attachment to be used with a new status.", description: "Creates an attachment to be used with a new status.",
operationId: "MediaController.update", operationId: "MediaController.update",
security: [%{"oAuth" => ["write:media"]}], security: [%{"oAuth" => ["write:media"]}],
@ -97,8 +97,8 @@ defp update_request do
def show_operation do def show_operation do
%Operation{ %Operation{
tags: ["media"], tags: ["Media attachments"],
summary: "Show Uploaded media attachment", summary: "Attachment",
operationId: "MediaController.show", operationId: "MediaController.show",
parameters: [id_param()], parameters: [id_param()],
security: [%{"oAuth" => ["read:media"]}], security: [%{"oAuth" => ["read:media"]}],
@ -112,8 +112,8 @@ def show_operation do
def create2_operation do def create2_operation do
%Operation{ %Operation{
tags: ["media"], tags: ["Media attachments"],
summary: "Upload media as attachment", summary: "Upload media as attachment (v2)",
description: "Creates an attachment to be used with a new status.", description: "Creates an attachment to be used with a new status.",
operationId: "MediaController.create2", operationId: "MediaController.create2",
security: [%{"oAuth" => ["write:media"]}], security: [%{"oAuth" => ["write:media"]}],

6
lib/pleroma/web/api_spec/operations/notification_operation.ex
View file

@ -22,7 +22,7 @@ def open_api_operation(action) do
def index_operation do def index_operation do
%Operation{ %Operation{
tags: ["Notifications"], tags: ["Notifications"],
summary: "Get all notifications", summary: "Retrieve a list of notifications",
description: description:
"Notifications concerning the user. This API returns Link headers containing links to the next/previous page. However, the links can also be constructed dynamically using query params and `id` values.", "Notifications concerning the user. This API returns Link headers containing links to the next/previous page. However, the links can also be constructed dynamically using query params and `id` values.",
operationId: "NotificationController.index", operationId: "NotificationController.index",
@ -74,7 +74,7 @@ def index_operation do
def show_operation do def show_operation do
%Operation{ %Operation{
tags: ["Notifications"], tags: ["Notifications"],
summary: "Get a single notification", summary: "Retrieve a notification",
description: "View information about a notification with a given ID.", description: "View information about a notification with a given ID.",
operationId: "NotificationController.show", operationId: "NotificationController.show",
security: [%{"oAuth" => ["read:notifications"]}], security: [%{"oAuth" => ["read:notifications"]}],
@ -99,7 +99,7 @@ def clear_operation do
def dismiss_operation do def dismiss_operation do
%Operation{ %Operation{
tags: ["Notifications"], tags: ["Notifications"],
summary: "Dismiss a single notification", summary: "Dismiss a notification",
description: "Clear a single notification from the server.", description: "Clear a single notification from the server.",
operationId: "NotificationController.dismiss", operationId: "NotificationController.dismiss",
parameters: [id_param()], parameters: [id_param()],

21
lib/pleroma/web/api_spec/operations/pleroma_account_operation.ex
View file

@ -18,8 +18,9 @@ def open_api_operation(action) do
def confirmation_resend_operation do def confirmation_resend_operation do
%Operation{ %Operation{
tags: ["Accounts"], tags: ["Account credentials"],
summary: "Resend confirmation email. Expects `email` or `nickname`", summary: "Resend confirmation email",
description: "Expects `email` or `nickname`.",
operationId: "PleromaAPI.AccountController.confirmation_resend", operationId: "PleromaAPI.AccountController.confirmation_resend",
parameters: [ parameters: [
Operation.parameter(:email, :query, :string, "Email of that needs to be verified", Operation.parameter(:email, :query, :string, "Email of that needs to be verified",
@ -41,8 +42,10 @@ def confirmation_resend_operation do
def favourites_operation do def favourites_operation do
%Operation{ %Operation{
tags: ["Accounts"], tags: ["Retrieve account information"],
summary: "Returns favorites timeline of any user", summary: "Favorites",
description:
"Only returns data if the user has opted into sharing it. See `hide_favorites` in [Update account credentials](#operation/AccountController.update_credentials).",
operationId: "PleromaAPI.AccountController.favourites", operationId: "PleromaAPI.AccountController.favourites",
parameters: [id_param() | pagination_params()], parameters: [id_param() | pagination_params()],
security: [%{"oAuth" => ["read:favourites"]}], security: [%{"oAuth" => ["read:favourites"]}],
@ -61,8 +64,9 @@ def favourites_operation do
def subscribe_operation do def subscribe_operation do
%Operation{ %Operation{
tags: ["Accounts"], tags: ["Account actions"],
summary: "Subscribe to receive notifications for all statuses posted by a user", summary: "Subscribe",
description: "Receive notifications for all statuses posted by the account.",
operationId: "PleromaAPI.AccountController.subscribe", operationId: "PleromaAPI.AccountController.subscribe",
parameters: [id_param()], parameters: [id_param()],
security: [%{"oAuth" => ["follow", "write:follows"]}], security: [%{"oAuth" => ["follow", "write:follows"]}],
@ -75,8 +79,9 @@ def subscribe_operation do
def unsubscribe_operation do def unsubscribe_operation do
%Operation{ %Operation{
tags: ["Accounts"], tags: ["Account actions"],
summary: "Unsubscribe to stop receiving notifications from user statuses", summary: "Unsubscribe",
description: "Stop receiving notifications for all statuses posted by the account.",
operationId: "PleromaAPI.AccountController.unsubscribe", operationId: "PleromaAPI.AccountController.unsubscribe",
parameters: [id_param()], parameters: [id_param()],
security: [%{"oAuth" => ["follow", "write:follows"]}], security: [%{"oAuth" => ["follow", "write:follows"]}],

9
lib/pleroma/web/api_spec/operations/pleroma_conversation_operation.ex
View file

@ -19,7 +19,7 @@ def open_api_operation(action) do
def show_operation do def show_operation do
%Operation{ %Operation{
tags: ["Conversations"], tags: ["Conversations"],
summary: "The conversation with the given ID", summary: "Conversation",
parameters: [ parameters: [
Operation.parameter(:id, :path, :string, "Conversation ID", Operation.parameter(:id, :path, :string, "Conversation ID",
example: "123", example: "123",
@ -37,7 +37,7 @@ def show_operation do
def statuses_operation do def statuses_operation do
%Operation{ %Operation{
tags: ["Conversations"], tags: ["Conversations"],
summary: "Timeline for a given conversation", summary: "Timeline for conversation",
parameters: [ parameters: [
Operation.parameter(:id, :path, :string, "Conversation ID", Operation.parameter(:id, :path, :string, "Conversation ID",
example: "123", example: "123",
@ -61,7 +61,8 @@ def statuses_operation do
def update_operation do def update_operation do
%Operation{ %Operation{
tags: ["Conversations"], tags: ["Conversations"],
summary: "Update a conversation. Used to change the set of recipients.", summary: "Update conversation",
description: "Change set of recipients for the conversation.",
parameters: [ parameters: [
Operation.parameter(:id, :path, :string, "Conversation ID", Operation.parameter(:id, :path, :string, "Conversation ID",
example: "123", example: "123",
@ -86,7 +87,7 @@ def update_operation do
def mark_as_read_operation do def mark_as_read_operation do
%Operation{ %Operation{
tags: ["Conversations"], tags: ["Conversations"],
summary: "Marks all user's conversations as read", summary: "Marks all conversations as read",
security: [%{"oAuth" => ["write:conversations"]}], security: [%{"oAuth" => ["write:conversations"]}],
operationId: "PleromaAPI.ConversationController.mark_as_read", operationId: "PleromaAPI.ConversationController.mark_as_read",
responses: %{ responses: %{

6
lib/pleroma/web/api_spec/operations/pleroma_emoji_file_operation.ex
View file

@ -16,7 +16,7 @@ def open_api_operation(action) do
def create_operation do def create_operation do
%Operation{ %Operation{
tags: ["Emoji Packs"], tags: ["Emoji packs"],
summary: "Add new file to the pack", summary: "Add new file to the pack",
operationId: "PleromaAPI.EmojiPackController.add_file", operationId: "PleromaAPI.EmojiPackController.add_file",
security: [%{"oAuth" => ["write"]}], security: [%{"oAuth" => ["write"]}],
@ -62,7 +62,7 @@ defp create_request do
def update_operation do def update_operation do
%Operation{ %Operation{
tags: ["Emoji Packs"], tags: ["Emoji packs"],
summary: "Add new file to the pack", summary: "Add new file to the pack",
operationId: "PleromaAPI.EmojiPackController.update_file", operationId: "PleromaAPI.EmojiPackController.update_file",
security: [%{"oAuth" => ["write"]}], security: [%{"oAuth" => ["write"]}],
@ -106,7 +106,7 @@ defp update_request do
def delete_operation do def delete_operation do
%Operation{ %Operation{
tags: ["Emoji Packs"], tags: ["Emoji packs"],
summary: "Delete emoji file from pack", summary: "Delete emoji file from pack",
operationId: "PleromaAPI.EmojiPackController.delete_file", operationId: "PleromaAPI.EmojiPackController.delete_file",
security: [%{"oAuth" => ["write"]}], security: [%{"oAuth" => ["write"]}],

18
lib/pleroma/web/api_spec/operations/pleroma_emoji_pack_operation.ex
View file

@ -16,7 +16,7 @@ def open_api_operation(action) do
def remote_operation do def remote_operation do
%Operation{ %Operation{
tags: ["Emoji Packs"], tags: ["Emoji packs"],
summary: "Make request to another instance for emoji packs list", summary: "Make request to another instance for emoji packs list",
security: [%{"oAuth" => ["write"]}], security: [%{"oAuth" => ["write"]}],
parameters: [ parameters: [
@ -44,7 +44,7 @@ def remote_operation do
def index_operation do def index_operation do
%Operation{ %Operation{
tags: ["Emoji Packs"], tags: ["Emoji packs"],
summary: "Lists local custom emoji packs", summary: "Lists local custom emoji packs",
operationId: "PleromaAPI.EmojiPackController.index", operationId: "PleromaAPI.EmojiPackController.index",
parameters: [ parameters: [
@ -69,7 +69,7 @@ def index_operation do
def show_operation do def show_operation do
%Operation{ %Operation{
tags: ["Emoji Packs"], tags: ["Emoji packs"],
summary: "Show emoji pack", summary: "Show emoji pack",
operationId: "PleromaAPI.EmojiPackController.show", operationId: "PleromaAPI.EmojiPackController.show",
parameters: [ parameters: [
@ -97,7 +97,7 @@ def show_operation do
def archive_operation do def archive_operation do
%Operation{ %Operation{
tags: ["Emoji Packs"], tags: ["Emoji packs"],
summary: "Requests a local pack archive from the instance", summary: "Requests a local pack archive from the instance",
operationId: "PleromaAPI.EmojiPackController.archive", operationId: "PleromaAPI.EmojiPackController.archive",
parameters: [name_param()], parameters: [name_param()],
@ -115,7 +115,7 @@ def archive_operation do
def download_operation do def download_operation do
%Operation{ %Operation{
tags: ["Emoji Packs"], tags: ["Emoji packs"],
summary: "Download pack from another instance", summary: "Download pack from another instance",
operationId: "PleromaAPI.EmojiPackController.download", operationId: "PleromaAPI.EmojiPackController.download",
security: [%{"oAuth" => ["write"]}], security: [%{"oAuth" => ["write"]}],
@ -145,7 +145,7 @@ defp download_request do
def create_operation do def create_operation do
%Operation{ %Operation{
tags: ["Emoji Packs"], tags: ["Emoji packs"],
summary: "Create an empty pack", summary: "Create an empty pack",
operationId: "PleromaAPI.EmojiPackController.create", operationId: "PleromaAPI.EmojiPackController.create",
security: [%{"oAuth" => ["write"]}], security: [%{"oAuth" => ["write"]}],
@ -161,7 +161,7 @@ def create_operation do
def delete_operation do def delete_operation do
%Operation{ %Operation{
tags: ["Emoji Packs"], tags: ["Emoji packs"],
summary: "Delete a custom emoji pack", summary: "Delete a custom emoji pack",
operationId: "PleromaAPI.EmojiPackController.delete", operationId: "PleromaAPI.EmojiPackController.delete",
security: [%{"oAuth" => ["write"]}], security: [%{"oAuth" => ["write"]}],
@ -177,7 +177,7 @@ def delete_operation do
def update_operation do def update_operation do
%Operation{ %Operation{
tags: ["Emoji Packs"], tags: ["Emoji packs"],
summary: "Updates (replaces) pack metadata", summary: "Updates (replaces) pack metadata",
operationId: "PleromaAPI.EmojiPackController.update", operationId: "PleromaAPI.EmojiPackController.update",
security: [%{"oAuth" => ["write"]}], security: [%{"oAuth" => ["write"]}],
@ -193,7 +193,7 @@ def update_operation do
def import_from_filesystem_operation do def import_from_filesystem_operation do
%Operation{ %Operation{
tags: ["Emoji Packs"], tags: ["Emoji packs"],
summary: "Imports packs from filesystem", summary: "Imports packs from filesystem",
operationId: "PleromaAPI.EmojiPackController.import", operationId: "PleromaAPI.EmojiPackController.import",
security: [%{"oAuth" => ["write"]}], security: [%{"oAuth" => ["write"]}],

4
lib/pleroma/web/api_spec/operations/pleroma_instances_operation.ex
View file

@ -13,8 +13,8 @@ def open_api_operation(action) do
def show_operation do def show_operation do
%Operation{ %Operation{
tags: ["PleromaInstances"], tags: ["Instance"],
summary: "Instances federation status", summary: "Retrieve federation status",
description: "Information about instances deemed unreachable by the server", description: "Information about instances deemed unreachable by the server",
operationId: "PleromaInstances.show", operationId: "PleromaInstances.show",
responses: %{ responses: %{

4
lib/pleroma/web/api_spec/operations/pleroma_mascot_operation.ex
View file

@ -17,7 +17,7 @@ def open_api_operation(action) do
def show_operation do def show_operation do
%Operation{ %Operation{
tags: ["Mascot"], tags: ["Mascot"],
summary: "Gets user mascot image", summary: "Retrieve mascot",
security: [%{"oAuth" => ["read:accounts"]}], security: [%{"oAuth" => ["read:accounts"]}],
operationId: "PleromaAPI.MascotController.show", operationId: "PleromaAPI.MascotController.show",
responses: %{ responses: %{
@ -29,7 +29,7 @@ def show_operation do
def update_operation do def update_operation do
%Operation{ %Operation{
tags: ["Mascot"], tags: ["Mascot"],
summary: "Set/clear user avatar image", summary: "Set or clear mascot",
description: description:
"Behaves exactly the same as `POST /api/v1/upload`. Can only accept images - any attempt to upload non-image files will be met with `HTTP 415 Unsupported Media Type`.", "Behaves exactly the same as `POST /api/v1/upload`. Can only accept images - any attempt to upload non-image files will be met with `HTTP 415 Unsupported Media Type`.",
operationId: "PleromaAPI.MascotController.update", operationId: "PleromaAPI.MascotController.update",

5
lib/pleroma/web/api_spec/operations/pleroma_notification_operation.ex
View file

@ -18,7 +18,8 @@ def open_api_operation(action) do
def mark_as_read_operation do def mark_as_read_operation do
%Operation{ %Operation{
tags: ["Notifications"], tags: ["Notifications"],
summary: "Mark notifications as read. Query parameters are mutually exclusive.", summary: "Mark notifications as read",
description: "Query parameters are mutually exclusive.",
requestBody: requestBody:
request_body("Parameters", %Schema{ request_body("Parameters", %Schema{
type: :object, type: :object,
@ -32,7 +33,7 @@ def mark_as_read_operation do
responses: %{ responses: %{
200 => 200 =>
Operation.response( Operation.response(
"A Notification or array of Motifications", "A Notification or array of Notifications",
"application/json", "application/json",
%Schema{ %Schema{
anyOf: [ anyOf: [

2
lib/pleroma/web/api_spec/operations/report_operation.ex
View file

@ -16,7 +16,7 @@ def open_api_operation(action) do
def create_operation do def create_operation do
%Operation{ %Operation{
tags: ["reports"], tags: ["Reports"],
summary: "File a report", summary: "File a report",
description: "Report problematic users to your moderators", description: "Report problematic users to your moderators",
operationId: "ReportController.create", operationId: "ReportController.create",

8
lib/pleroma/web/api_spec/operations/scheduled_activity_operation.ex
View file

@ -18,7 +18,7 @@ def open_api_operation(action) do
def index_operation do def index_operation do
%Operation{ %Operation{
tags: ["Scheduled Statuses"], tags: ["Scheduled statuses"],
summary: "View scheduled statuses", summary: "View scheduled statuses",
security: [%{"oAuth" => ["read:statuses"]}], security: [%{"oAuth" => ["read:statuses"]}],
parameters: pagination_params(), parameters: pagination_params(),
@ -35,7 +35,7 @@ def index_operation do
def show_operation do def show_operation do
%Operation{ %Operation{
tags: ["Scheduled Statuses"], tags: ["Scheduled statuses"],
summary: "View a single scheduled status", summary: "View a single scheduled status",
security: [%{"oAuth" => ["read:statuses"]}], security: [%{"oAuth" => ["read:statuses"]}],
parameters: [id_param()], parameters: [id_param()],
@ -49,7 +49,7 @@ def show_operation do
def update_operation do def update_operation do
%Operation{ %Operation{
tags: ["Scheduled Statuses"], tags: ["Scheduled statuses"],
summary: "Schedule a status", summary: "Schedule a status",
operationId: "ScheduledActivity.update", operationId: "ScheduledActivity.update",
security: [%{"oAuth" => ["write:statuses"]}], security: [%{"oAuth" => ["write:statuses"]}],
@ -75,7 +75,7 @@ def update_operation do
def delete_operation do def delete_operation do
%Operation{ %Operation{
tags: ["Scheduled Statuses"], tags: ["Scheduled statuses"],
summary: "Cancel a scheduled status", summary: "Cancel a scheduled status",
security: [%{"oAuth" => ["write:statuses"]}], security: [%{"oAuth" => ["write:statuses"]}],
parameters: [id_param()], parameters: [id_param()],

56
lib/pleroma/web/api_spec/operations/status_operation.ex
View file

@ -22,8 +22,8 @@ def open_api_operation(action) do
def index_operation do def index_operation do
%Operation{ %Operation{
tags: ["Statuses"], tags: ["Retrieve status information"],
summary: "Get multiple statuses by IDs", summary: "Multiple statuses",
security: [%{"oAuth" => ["read:statuses"]}], security: [%{"oAuth" => ["read:statuses"]}],
parameters: [ parameters: [
Operation.parameter( Operation.parameter(
@ -48,7 +48,7 @@ def index_operation do
def create_operation do def create_operation do
%Operation{ %Operation{
tags: ["Statuses"], tags: ["Status actions"],
summary: "Publish new status", summary: "Publish new status",
security: [%{"oAuth" => ["write:statuses"]}], security: [%{"oAuth" => ["write:statuses"]}],
description: "Post a new status", description: "Post a new status",
@ -68,8 +68,8 @@ def create_operation do
def show_operation do def show_operation do
%Operation{ %Operation{
tags: ["Statuses"], tags: ["Retrieve status information"],
summary: "View specific status", summary: "Status",
description: "View information about a status", description: "View information about a status",
operationId: "StatusController.show", operationId: "StatusController.show",
security: [%{"oAuth" => ["read:statuses"]}], security: [%{"oAuth" => ["read:statuses"]}],
@ -91,8 +91,8 @@ def show_operation do
def delete_operation do def delete_operation do
%Operation{ %Operation{
tags: ["Statuses"], tags: ["Status actions"],
summary: "Delete status", summary: "Delete",
security: [%{"oAuth" => ["write:statuses"]}], security: [%{"oAuth" => ["write:statuses"]}],
description: "Delete one of your own statuses", description: "Delete one of your own statuses",
operationId: "StatusController.delete", operationId: "StatusController.delete",
@ -107,8 +107,8 @@ def delete_operation do
def reblog_operation do def reblog_operation do
%Operation{ %Operation{
tags: ["Statuses"], tags: ["Status actions"],
summary: "Boost", summary: "Reblog",
security: [%{"oAuth" => ["write:statuses"]}], security: [%{"oAuth" => ["write:statuses"]}],
description: "Share a status", description: "Share a status",
operationId: "StatusController.reblog", operationId: "StatusController.reblog",
@ -129,8 +129,8 @@ def reblog_operation do
def unreblog_operation do def unreblog_operation do
%Operation{ %Operation{
tags: ["Statuses"], tags: ["Status actions"],
summary: "Undo boost", summary: "Undo reblog",
security: [%{"oAuth" => ["write:statuses"]}], security: [%{"oAuth" => ["write:statuses"]}],
description: "Undo a reshare of a status", description: "Undo a reshare of a status",
operationId: "StatusController.unreblog", operationId: "StatusController.unreblog",
@ -144,7 +144,7 @@ def unreblog_operation do
def favourite_operation do def favourite_operation do
%Operation{ %Operation{
tags: ["Statuses"], tags: ["Status actions"],
summary: "Favourite", summary: "Favourite",
security: [%{"oAuth" => ["write:favourites"]}], security: [%{"oAuth" => ["write:favourites"]}],
description: "Add a status to your favourites list", description: "Add a status to your favourites list",
@ -159,7 +159,7 @@ def favourite_operation do
def unfavourite_operation do def unfavourite_operation do
%Operation{ %Operation{
tags: ["Statuses"], tags: ["Status actions"],
summary: "Undo favourite", summary: "Undo favourite",
security: [%{"oAuth" => ["write:favourites"]}], security: [%{"oAuth" => ["write:favourites"]}],
description: "Remove a status from your favourites list", description: "Remove a status from your favourites list",
@ -174,7 +174,7 @@ def unfavourite_operation do
def pin_operation do def pin_operation do
%Operation{ %Operation{
tags: ["Statuses"], tags: ["Status actions"],
summary: "Pin to profile", summary: "Pin to profile",
security: [%{"oAuth" => ["write:accounts"]}], security: [%{"oAuth" => ["write:accounts"]}],
description: "Feature one of your own public statuses at the top of your profile", description: "Feature one of your own public statuses at the top of your profile",
@ -189,8 +189,8 @@ def pin_operation do
def unpin_operation do def unpin_operation do
%Operation{ %Operation{
tags: ["Statuses"], tags: ["Status actions"],
summary: "Unpin to profile", summary: "Unpin from profile",
security: [%{"oAuth" => ["write:accounts"]}], security: [%{"oAuth" => ["write:accounts"]}],
description: "Unfeature a status from the top of your profile", description: "Unfeature a status from the top of your profile",
operationId: "StatusController.unpin", operationId: "StatusController.unpin",
@ -204,7 +204,7 @@ def unpin_operation do
def bookmark_operation do def bookmark_operation do
%Operation{ %Operation{
tags: ["Statuses"], tags: ["Status actions"],
summary: "Bookmark", summary: "Bookmark",
security: [%{"oAuth" => ["write:bookmarks"]}], security: [%{"oAuth" => ["write:bookmarks"]}],
description: "Privately bookmark a status", description: "Privately bookmark a status",
@ -218,7 +218,7 @@ def bookmark_operation do
def unbookmark_operation do def unbookmark_operation do
%Operation{ %Operation{
tags: ["Statuses"], tags: ["Status actions"],
summary: "Undo bookmark", summary: "Undo bookmark",
security: [%{"oAuth" => ["write:bookmarks"]}], security: [%{"oAuth" => ["write:bookmarks"]}],
description: "Remove a status from your private bookmarks", description: "Remove a status from your private bookmarks",
@ -232,7 +232,7 @@ def unbookmark_operation do
def mute_conversation_operation do def mute_conversation_operation do
%Operation{ %Operation{
tags: ["Statuses"], tags: ["Status actions"],
summary: "Mute conversation", summary: "Mute conversation",
security: [%{"oAuth" => ["write:mutes"]}], security: [%{"oAuth" => ["write:mutes"]}],
description: "Do not receive notifications for the thread that this status is part of.", description: "Do not receive notifications for the thread that this status is part of.",
@ -267,7 +267,7 @@ def mute_conversation_operation do
def unmute_conversation_operation do def unmute_conversation_operation do
%Operation{ %Operation{
tags: ["Statuses"], tags: ["Status actions"],
summary: "Unmute conversation", summary: "Unmute conversation",
security: [%{"oAuth" => ["write:mutes"]}], security: [%{"oAuth" => ["write:mutes"]}],
description: description:
@ -283,7 +283,7 @@ def unmute_conversation_operation do
def card_operation do def card_operation do
%Operation{ %Operation{
tags: ["Statuses"], tags: ["Retrieve status information"],
deprecated: true, deprecated: true,
summary: "Preview card", summary: "Preview card",
description: "Deprecated in favor of card property inlined on Status entity", description: "Deprecated in favor of card property inlined on Status entity",
@ -311,7 +311,7 @@ def card_operation do
def favourited_by_operation do def favourited_by_operation do
%Operation{ %Operation{
tags: ["Statuses"], tags: ["Retrieve status information"],
summary: "Favourited by", summary: "Favourited by",
description: "View who favourited a given status", description: "View who favourited a given status",
operationId: "StatusController.favourited_by", operationId: "StatusController.favourited_by",
@ -331,9 +331,9 @@ def favourited_by_operation do
def reblogged_by_operation do def reblogged_by_operation do
%Operation{ %Operation{
tags: ["Statuses"], tags: ["Retrieve status information"],
summary: "Boosted by", summary: "Reblogged by",
description: "View who boosted a given status", description: "View who reblogged a given status",
operationId: "StatusController.reblogged_by", operationId: "StatusController.reblogged_by",
security: [%{"oAuth" => ["read:accounts"]}], security: [%{"oAuth" => ["read:accounts"]}],
parameters: [id_param()], parameters: [id_param()],
@ -351,7 +351,7 @@ def reblogged_by_operation do
def context_operation do def context_operation do
%Operation{ %Operation{
tags: ["Statuses"], tags: ["Retrieve status information"],
summary: "Parent and child statuses", summary: "Parent and child statuses",
description: "View statuses above and below this status in the thread", description: "View statuses above and below this status in the thread",
operationId: "StatusController.context", operationId: "StatusController.context",
@ -365,7 +365,7 @@ def context_operation do
def favourites_operation do def favourites_operation do
%Operation{ %Operation{
tags: ["Statuses"], tags: ["Timelines"],
summary: "Favourited statuses", summary: "Favourited statuses",
description: description:
"Statuses the user has favourited. Please note that you have to use the link headers to paginate this. You can not build the query parameters yourself.", "Statuses the user has favourited. Please note that you have to use the link headers to paginate this. You can not build the query parameters yourself.",
@ -380,7 +380,7 @@ def favourites_operation do
def bookmarks_operation do def bookmarks_operation do
%Operation{ %Operation{
tags: ["Statuses"], tags: ["Timelines"],
summary: "Bookmarked statuses", summary: "Bookmarked statuses",
description: "Statuses the user has bookmarked", description: "Statuses the user has bookmarked",
operationId: "StatusController.bookmarks", operationId: "StatusController.bookmarks",

14
lib/pleroma/web/api_spec/operations/subscription_operation.ex
View file

@ -17,7 +17,7 @@ def open_api_operation(action) do
def create_operation do def create_operation do
%Operation{ %Operation{
tags: ["Push Subscriptions"], tags: ["Push subscriptions"],
summary: "Subscribe to push notifications", summary: "Subscribe to push notifications",
description: description:
"Add a Web Push API subscription to receive notifications. Each access token can have one push subscription. If you create a new subscription, the old subscription is deleted.", "Add a Web Push API subscription to receive notifications. Each access token can have one push subscription. If you create a new subscription, the old subscription is deleted.",
@ -25,7 +25,7 @@ def create_operation do
security: [%{"oAuth" => ["push"]}], security: [%{"oAuth" => ["push"]}],
requestBody: Helpers.request_body("Parameters", create_request(), required: true), requestBody: Helpers.request_body("Parameters", create_request(), required: true),
responses: %{ responses: %{
200 => Operation.response("Push Subscription", "application/json", PushSubscription), 200 => Operation.response("Push subscription", "application/json", PushSubscription),
400 => Operation.response("Error", "application/json", ApiError), 400 => Operation.response("Error", "application/json", ApiError),
403 => Operation.response("Error", "application/json", ApiError) 403 => Operation.response("Error", "application/json", ApiError)
} }
@ -34,13 +34,13 @@ def create_operation do
def show_operation do def show_operation do
%Operation{ %Operation{
tags: ["Push Subscriptions"], tags: ["Push subscriptions"],
summary: "Get current subscription", summary: "Get current subscription",
description: "View the PushSubscription currently associated with this access token.", description: "View the PushSubscription currently associated with this access token.",
operationId: "SubscriptionController.show", operationId: "SubscriptionController.show",
security: [%{"oAuth" => ["push"]}], security: [%{"oAuth" => ["push"]}],
responses: %{ responses: %{
200 => Operation.response("Push Subscription", "application/json", PushSubscription), 200 => Operation.response("Push subscription", "application/json", PushSubscription),
403 => Operation.response("Error", "application/json", ApiError), 403 => Operation.response("Error", "application/json", ApiError),
404 => Operation.response("Error", "application/json", ApiError) 404 => Operation.response("Error", "application/json", ApiError)
} }
@ -49,7 +49,7 @@ def show_operation do
def update_operation do def update_operation do
%Operation{ %Operation{
tags: ["Push Subscriptions"], tags: ["Push subscriptions"],
summary: "Change types of notifications", summary: "Change types of notifications",
description: description:
"Updates the current push subscription. Only the data part can be updated. To change fundamentals, a new subscription must be created instead.", "Updates the current push subscription. Only the data part can be updated. To change fundamentals, a new subscription must be created instead.",
@ -57,7 +57,7 @@ def update_operation do
security: [%{"oAuth" => ["push"]}], security: [%{"oAuth" => ["push"]}],
requestBody: Helpers.request_body("Parameters", update_request(), required: true), requestBody: Helpers.request_body("Parameters", update_request(), required: true),
responses: %{ responses: %{
200 => Operation.response("Push Subscription", "application/json", PushSubscription), 200 => Operation.response("Push subscription", "application/json", PushSubscription),
403 => Operation.response("Error", "application/json", ApiError) 403 => Operation.response("Error", "application/json", ApiError)
} }
} }
@ -65,7 +65,7 @@ def update_operation do
def delete_operation do def delete_operation do
%Operation{ %Operation{
tags: ["Push Subscriptions"], tags: ["Push subscriptions"],
summary: "Remove current subscription", summary: "Remove current subscription",
description: "Removes the current Web Push API subscription.", description: "Removes the current Web Push API subscription.",
operationId: "SubscriptionController.delete", operationId: "SubscriptionController.delete",

3
lib/pleroma/web/api_spec/operations/timeline_operation.ex
View file

@ -41,8 +41,7 @@ def direct_operation do
tags: ["Timelines"], tags: ["Timelines"],
summary: "Direct timeline", summary: "Direct timeline",
description: description:
"View statuses with a “direct” privacy, from your account or in your notifications", "View statuses with a “direct” scope addressed to the account. Using this endpoint is discouraged, please use [conversations](#tag/Conversations) or [chats](#tag/Chats).",
deprecated: true,
parameters: [with_muted_param() | pagination_params()], parameters: [with_muted_param() | pagination_params()],
security: [%{"oAuth" => ["read:statuses"]}], security: [%{"oAuth" => ["read:statuses"]}],
operationId: "TimelineController.direct", operationId: "TimelineController.direct",

12
lib/pleroma/web/api_spec/operations/user_import_operation.ex
View file

@ -17,8 +17,8 @@ def open_api_operation(action) do
def follow_operation do def follow_operation do
%Operation{ %Operation{
tags: ["follow_import"], tags: ["Data import"],
summary: "Imports your follows.", summary: "Import follows",
operationId: "UserImportController.follow", operationId: "UserImportController.follow",
requestBody: request_body("Parameters", import_request(), required: true), requestBody: request_body("Parameters", import_request(), required: true),
responses: %{ responses: %{
@ -31,8 +31,8 @@ def follow_operation do
def blocks_operation do def blocks_operation do
%Operation{ %Operation{
tags: ["blocks_import"], tags: ["Data import"],
summary: "Imports your blocks.", summary: "Import blocks",
operationId: "UserImportController.blocks", operationId: "UserImportController.blocks",
requestBody: request_body("Parameters", import_request(), required: true), requestBody: request_body("Parameters", import_request(), required: true),
responses: %{ responses: %{
@ -45,8 +45,8 @@ def blocks_operation do
def mutes_operation do def mutes_operation do
%Operation{ %Operation{
tags: ["mutes_import"], tags: ["Data import"],
summary: "Imports your mutes.", summary: "Import mutes",
operationId: "UserImportController.mutes", operationId: "UserImportController.mutes",
requestBody: request_body("Parameters", import_request(), required: true), requestBody: request_body("Parameters", import_request(), required: true),
responses: %{ responses: %{