Commit 9fcff785 authored by rinpatch's avatar rinpatch
Browse files

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

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.
parent ba40af05
Pipeline #34624 passed with stages
in 6 minutes and 52 seconds
......@@ -34,6 +34,14 @@ build:
- mix deps.get
- mix compile --force
spec-build:
stage: test
artifacts:
paths:
- spec.json
script:
- mix pleroma.openapi_spec spec.json
benchmark:
stage: benchmark
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
- 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:
image: alpine:3.9
stage: deploy
......
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
......@@ -11,10 +11,10 @@ defmodule Pleroma.Web.ApiSpec do
@behaviour OpenApi
@impl OpenApi
def spec do
def spec(opts \\ []) do
%OpenApi{
servers:
if Phoenix.Endpoint.server?(:pleroma, Endpoint) do
if opts[:server_specific] do
[
# Populate the Server info from a phoenix endpoint
OpenApiSpex.Server.from_endpoint(Endpoint)
......@@ -23,9 +23,25 @@ def spec do
[]
end,
info: %OpenApiSpex.Info{
title: "Pleroma",
description: Application.spec(:pleroma, :description) |> to_string(),
version: Application.spec(:pleroma, :vsn) |> to_string()
title: "Pleroma API",
description: """
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
paths: OpenApiSpex.Paths.from_router(Router),
......@@ -45,15 +61,73 @@ def spec do
authorizationUrl: "/oauth/authorize",
tokenUrl: "/oauth/token",
scopes: %{
"read" => "read",
"write" => "write",
"follow" => "follow",
"push" => "push"
# TODO: Document granular scopes
"read" => "Read everything",
"write" => "Write everything",
"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
......
......@@ -26,7 +26,7 @@ def open_api_operation(action) do
@spec create_operation() :: Operation.t()
def create_operation do
%Operation{
tags: ["accounts"],
tags: ["Account credentials"],
summary: "Register an account",
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.",
......@@ -43,7 +43,7 @@ def create_operation do
def verify_credentials_operation do
%Operation{
tags: ["accounts"],
tags: ["Account credentials"],
description: "Test to make sure that the user token works.",
summary: "Verify account credentials",
operationId: "AccountController.verify_credentials",
......@@ -56,7 +56,7 @@ def verify_credentials_operation do
def update_credentials_operation do
%Operation{
tags: ["accounts"],
tags: ["Account credentials"],
summary: "Update account credentials",
description: "Update the user's display and preferences.",
operationId: "AccountController.update_credentials",
......@@ -71,8 +71,8 @@ def update_credentials_operation do
def relationships_operation do
%Operation{
tags: ["accounts"],
summary: "Check relationships to other accounts",
tags: ["Retrieve account information"],
summary: "Relationship with current account",
operationId: "AccountController.relationships",
description: "Find out whether a given account is followed, blocked, muted, etc.",
security: [%{"oAuth" => ["read:follows"]}],
......@@ -95,7 +95,7 @@ def relationships_operation do
def show_operation do
%Operation{
tags: ["accounts"],
tags: ["Retrieve account information"],
summary: "Account",
operationId: "AccountController.show",
description: "View information about a profile.",
......@@ -110,8 +110,8 @@ def show_operation do
def statuses_operation do
%Operation{
tags: ["accounts"],
summary: "Statuses",
tags: ["Retrieve account information"],
operationId: "AccountController.statuses",
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)",
......@@ -157,7 +157,7 @@ def statuses_operation do
def followers_operation do
%Operation{
tags: ["accounts"],
tags: ["Retrieve account information"],
summary: "Followers",
operationId: "AccountController.followers",
security: [%{"oAuth" => ["read:accounts"]}],
......@@ -176,7 +176,7 @@ def followers_operation do
def following_operation do
%Operation{
tags: ["accounts"],
tags: ["Retrieve account information"],
summary: "Following",
operationId: "AccountController.following",
security: [%{"oAuth" => ["read:accounts"]}],
......@@ -193,7 +193,7 @@ def following_operation do
def lists_operation do
%Operation{
tags: ["accounts"],
tags: ["Retrieve account information"],
summary: "Lists containing this account",
operationId: "AccountController.lists",
security: [%{"oAuth" => ["read:lists"]}],
......@@ -205,7 +205,7 @@ def lists_operation do
def follow_operation do
%Operation{
tags: ["accounts"],
tags: ["Account actions"],
summary: "Follow",
operationId: "AccountController.follow",
security: [%{"oAuth" => ["follow", "write:follows"]}],
......@@ -238,7 +238,7 @@ def follow_operation do
def unfollow_operation do
%Operation{
tags: ["accounts"],
tags: ["Account actions"],
summary: "Unfollow",
operationId: "AccountController.unfollow",
security: [%{"oAuth" => ["follow", "write:follows"]}],
......@@ -254,7 +254,7 @@ def unfollow_operation do
def mute_operation do
%Operation{
tags: ["accounts"],
tags: ["Account actions"],
summary: "Mute",
operationId: "AccountController.mute",
security: [%{"oAuth" => ["follow", "write:mutes"]}],
......@@ -284,7 +284,7 @@ def mute_operation do
def unmute_operation do
%Operation{
tags: ["accounts"],
tags: ["Account actions"],
summary: "Unmute",
operationId: "AccountController.unmute",
security: [%{"oAuth" => ["follow", "write:mutes"]}],
......@@ -298,7 +298,7 @@ def unmute_operation do
def block_operation do
%Operation{
tags: ["accounts"],
tags: ["Account actions"],
summary: "Block",
operationId: "AccountController.block",
security: [%{"oAuth" => ["follow", "write:blocks"]}],
......@@ -313,7 +313,7 @@ def block_operation do
def unblock_operation do
%Operation{
tags: ["accounts"],
tags: ["Account actions"],
summary: "Unblock",
operationId: "AccountController.unblock",
security: [%{"oAuth" => ["follow", "write:blocks"]}],
......@@ -327,7 +327,7 @@ def unblock_operation do
def follow_by_uri_operation do
%Operation{
tags: ["accounts"],
tags: ["Account actions"],
summary: "Follow by URI",
operationId: "AccountController.follows",
security: [%{"oAuth" => ["follow", "write:follows"]}],
......@@ -342,8 +342,8 @@ def follow_by_uri_operation do
def mutes_operation do
%Operation{
tags: ["accounts"],
summary: "Muted accounts",
tags: ["Blocks and mutes"],
summary: "Retrieve list of mutes",
operationId: "AccountController.mutes",
description: "Accounts the user has muted.",
security: [%{"oAuth" => ["follow", "read:mutes"]}],
......@@ -356,8 +356,8 @@ def mutes_operation do
def blocks_operation do
%Operation{
tags: ["accounts"],
summary: "Blocked users",
tags: ["Blocks and mutes"],
summary: "Retrieve list of blocks",
operationId: "AccountController.blocks",
description: "View your blocks. See also accounts/:id/{block,unblock}",
security: [%{"oAuth" => ["read:blocks"]}],
......@@ -370,7 +370,7 @@ def blocks_operation do
def endorsements_operation do
%Operation{
tags: ["accounts"],
tags: ["Retrieve account information"],
summary: "Endorsements",
operationId: "AccountController.endorsements",
description: "Not implemented",
......@@ -383,7 +383,7 @@ def endorsements_operation do
def identity_proofs_operation do
%Operation{
tags: ["accounts"],
tags: ["Retrieve account information"],
summary: "Identity proofs",
operationId: "AccountController.identity_proofs",
# Validators complains about unused path params otherwise
......
......@@ -16,7 +16,7 @@ def open_api_operation(action) do
def delete_message_operation do
%Operation{
tags: ["admin", "chat"],
tags: ["Chat administration"],
summary: "Delete an individual chat message",
operationId: "AdminAPI.ChatController.delete_message",
parameters: [
......@@ -41,8 +41,8 @@ def delete_message_operation do
def messages_operation do
%Operation{
tags: ["admin", "chat"],
summary: "Get the most recent messages of the chat",
tags: ["Chat administration"],
summary: "Get chat's messages",
operationId: "AdminAPI.ChatController.messages",
parameters:
[Operation.parameter(:id, :path, :string, "The ID of the Chat")] ++
......@@ -65,7 +65,7 @@ def messages_operation do
def show_operation do
%Operation{
tags: ["chat"],
tags: ["Chat administration"],
summary: "Create a chat",
operationId: "AdminAPI.ChatController.show",
parameters: [
......
......@@ -16,8 +16,8 @@ def open_api_operation(action) do
def show_operation do
%Operation{
tags: ["Admin", "Config"],
summary: "Get list of merged default settings with saved in database",
tags: ["Instance configuration"],
summary: "Retrieve instance configuration",
operationId: "AdminAPI.ConfigController.show",
parameters: [
Operation.parameter(
......@@ -38,8 +38,8 @@ def show_operation do
def update_operation do
%Operation{
tags: ["Admin", "Config"],
summary: "Update config settings",
tags: ["Instance configuration"],
summary: "Update instance configuration",
operationId: "AdminAPI.ConfigController.update",
security: [%{"oAuth" => ["write"]}],
parameters: admin_api_params(),
......@@ -71,8 +71,8 @@ def update_operation do
def descriptions_operation do
%Operation{
tags: ["Admin", "Config"],
summary: "Get JSON with config descriptions.",
tags: ["Instance configuration"],
summary: "Retrieve config description",
operationId: "AdminAPI.ConfigController.descriptions",
security: [%{"oAuth" => ["read"]}],
parameters: admin_api_params(),
......
......@@ -16,8 +16,8 @@ def open_api_operation(action) do
def index_operation do
%Operation{
tags: ["Admin", "Reports"],
summary: "Get a list of available frontends",
tags: ["Frontend managment"],
summary: "Retrieve a list of available frontends",
operationId: "AdminAPI.FrontendController.index",
security: [%{"oAuth" => ["read"]}],
responses: %{
......@@ -29,7 +29,7 @@ def index_operation do
def install_operation do
%Operation{
tags: ["Admin", "Reports"],
tags: ["Frontend managment"],
summary: "Install a frontend",
operationId: "AdminAPI.FrontendController.install",
security: [%{"oAuth" => ["read"]}],
......
......@@ -15,8 +15,8 @@ def open_api_operation(action) do
def show_operation do
%Operation{
tags: ["Admin", "InstanceDocument"],
summary: "Get the instance document",
tags: ["Instance documents"],
summary: "Retrieve an instance document",
operationId: "AdminAPI.InstanceDocumentController.show",
security: [%{"oAuth" => ["read"]}],
parameters: [
......@@ -36,8 +36,8 @@ def show_operation do
def update_operation do
%Operation{
tags: ["Admin", "InstanceDocument"],
summary: "Update the instance document",
tags: ["Instance documents"],
summary: "Update an instance document",
operationId: "AdminAPI.InstanceDocumentController.update",
security: [%{"oAuth" => ["write"]}],
requestBody: Helpers.request_body("Parameters", update_request()),
......@@ -74,8 +74,8 @@ defp update_request do
def delete_operation do
%Operation{
tags: ["Admin", "InstanceDocument"],
summary: "Get the instance document",
tags: ["Instance documents"],
summary: "Delete an instance document",
operationId: "AdminAPI.InstanceDocumentController.delete",
security: [%{"oAuth" => ["write"]}],
parameters: [
......
......@@ -16,7 +16,7 @@ def open_api_operation(action) do
def index_operation do
%Operation{
tags: ["Admin", "Invites"],
tags: ["Invites"],
summary: "Get a list of generated invites",
operationId: "AdminAPI.InviteController.index",
security: [%{"oAuth" => ["read:invites"]}],
......@@ -48,7 +48,7 @@ def index_operation do
def create_operation do
%Operation{
tags: ["Admin", "Invites"],
tags: ["Invites"],
summary: "Create an account registration invite token",
operationId: "AdminAPI.InviteController.create",
security: [%{"oAuth" => ["write:invites"]}],
......@@ -69,7 +69,7 @@ def create_operation do
def revoke_operation do
%Operation{
tags: ["Admin", "Invites"],
tags: ["Invites"],
summary: "Revoke invite by token",
operationId: "AdminAPI.InviteController.revoke",
security: [%{"oAuth" => ["write:invites"]}],
......@@ -96,7 +96,7 @@ def revoke_operation do
def email_operation do
%Operation{
tags: ["Admin", "Invites"],
tags: ["Invites"],
summary: "Sends registration invite via email",
operationId: "AdminAPI.InviteController.email",
security: [%{"oAuth" => ["write:invites"]}],
......
......@@ -16,8 +16,8 @@ def open_api_operation(action) do
def index_operation do
%Operation{
tags: ["Admin", "MediaProxyCache"],
summary: "Fetch a paginated list of all banned MediaProxy URLs in Cachex",
tags: ["MediaProxy cache"],
summary: "Retrieve a list of banned MediaProxy URLs",
operationId: "AdminAPI.MediaProxyCacheController.index",
security: [%{"oAuth" => ["read:media_proxy_caches"]}],
parameters: [
......@@ -44,7 +44,7 @@ def index_operation do
responses: %{
200 =>
Operation.response(
"Array of banned MediaProxy URLs in Cachex",
"Array of MediaProxy URLs",
"application/json",
%Schema{
type: :object,
......@@ -68,8 +68,8 @@ def index_operation do
def delete_operation do
%Operation{
tags: ["Admin", "MediaProxyCache"],
summary: "Remove a banned MediaProxy URL from Cachex",
tags: ["MediaProxy cache"],
summary: "Remove a banned MediaProxy URL",
operationId: "AdminAPI.MediaProxyCacheController.delete",
security: [%{"oAuth" => ["write:media_proxy_caches"]}],
parameters: admin_api_params(),
......@@ -94,8 +94,8 @@ def delete_operation do
def purge_operation do
%Operation{
tags: ["Admin", "MediaProxyCache"],
summary: "Purge and optionally ban a MediaProxy URL",
tags: ["MediaProxy cache"],
summary: "Purge a URL from MediaProxy cache and optionally ban it",
operationId: "AdminAPI.MediaProxyCacheController.purge",
security: [%{"oAuth" => ["write:media_proxy_caches"]}],
parameters: admin_api_params(),
......
......@@ -16,8 +16,8 @@ def open_api_operation(action) do
def index_operation do
%Operation{
summary: "List OAuth apps",
tags: ["Admin", "oAuth Apps"],
summary: "Retrieve a list of OAuth applications",
tags: ["OAuth application managment"],
operationId: "AdminAPI.OAuthAppController.index",
security: [%{"oAuth" => ["write"]}],
parameters: [
......@@ -69,8 +69,8 @@ def index_operation do
def create_operation do
%Operation{
tags: ["Admin", "oAuth Apps"],
summary: "Create OAuth App",
tags: ["OAuth application managment"],
summary: "Create an OAuth application",
operationId: "AdminAPI.OAuthAppController.create",
requestBody: request_body("Parameters", create_request()),
parameters: admin_api_params(),
......@@ -84,8 +84,8 @@ def create_operation do
def update_operation do
%Operation{
tags: ["Admin", "oAuth Apps"],
summary: "Update OAuth App",
tags: ["OAuth application managment"],
summary: "Update OAuth application",
operationId: "AdminAPI.OAuthAppController.update",
parameters: [id_param() | admin_api_params()],
security: [%{"oAuth" => ["write"]}],
......@@ -102,8 +102,8 @@ def update_operation do
def delete_operation do
%Operation{
tags: ["Admin", "oAuth Apps"],
summary: "Delete OAuth App",
tags: ["OAuth application managment"],
summary: "Delete OAuth application",
operationId: "AdminAPI.OAuthAppController.delete",
parameters: [id_param() | admin_api_params()],
security: [%{"oAuth" => ["write"]}],
......
......@@ -15,8 +15,8 @@ def open_api_operation(action) do
def index_operation do
%Operation{
tags: ["Admin", "Relays"],
summary: "List Relays",
tags: ["Relays"],
summary: "Retrieve a list of relays",
operationId: "AdminAPI.RelayController.index",
security: [%{"oAuth" => ["read"]}],
parameters: admin_api_params(),
......@@ -37,8 +37,8 @@ def index_operation do
def follow_operation do
%Operation{
tags: ["Admin", "Relays"],
summary: "Follow a Relay",
tags: ["Relays"],
summary: "Follow a relay",
operationId: "AdminAPI.RelayController.follow",
security: [%{"oAuth" => ["write:follows"]}],
parameters: admin_api_params(),
......@@ -51,8 +51,8 @@ def follow_operation do
def unfollow_operation do
%Operation{
tags: ["Admin", "Relays"],
summary: "Unfollow a Relay",
tags: ["Relays"],
summary: "Unfollow a relay",
operationId: "AdminAPI.RelayController.unfollow",
security: [%{"oAuth" => ["write:follows"]}],