From e090191d03b21020a75c1ef91a200c3e4807c2d1 Mon Sep 17 00:00:00 2001 From: Egor Kislitsyn Date: Fri, 15 May 2020 14:55:41 +0400 Subject: [PATCH] [OpenAPI] Mark all not required request fields as nullable --- .../api_spec/operations/account_operation.ex | 54 ++++++++++++++++--- .../web/api_spec/operations/app_operation.ex | 6 ++- .../api_spec/operations/filter_operation.ex | 6 ++- .../api_spec/operations/marker_operation.ex | 6 ++- .../operations/pleroma_account_operation.ex | 2 + .../api_spec/operations/report_operation.ex | 3 ++ .../api_spec/operations/status_operation.ex | 26 ++++++++- .../operations/subscription_operation.ex | 54 ++++++++++++++++--- 8 files changed, 134 insertions(+), 23 deletions(-) diff --git a/lib/pleroma/web/api_spec/operations/account_operation.ex b/lib/pleroma/web/api_spec/operations/account_operation.ex index 70069d6f9..988bab882 100644 --- a/lib/pleroma/web/api_spec/operations/account_operation.ex +++ b/lib/pleroma/web/api_spec/operations/account_operation.ex @@ -367,15 +367,18 @@ defmodule Pleroma.Web.ApiSpec.AccountOperation do title: "AccountCreateRequest", description: "POST body for creating an account", type: :object, + required: [:username, :password, :agreement], properties: %{ reason: %Schema{ type: :string, + nullable: true, description: "Text that will be reviewed by moderators if registrations require manual approval" }, username: %Schema{type: :string, description: "The desired username for the account"}, email: %Schema{ type: :string, + nullable: true, description: "The email address to be used for login. Required when `account_activation_required` is enabled.", format: :email @@ -392,23 +395,33 @@ defmodule Pleroma.Web.ApiSpec.AccountOperation do }, locale: %Schema{ type: :string, + nullable: true, description: "The language of the confirmation email that will be sent" }, # Pleroma-specific properties: - fullname: %Schema{type: :string, description: "Full name"}, - bio: %Schema{type: :string, description: "Bio", default: ""}, + fullname: %Schema{type: :string, nullable: true, description: "Full name"}, + bio: %Schema{type: :string, description: "Bio", nullable: true, default: ""}, captcha_solution: %Schema{ type: :string, + nullable: true, description: "Provider-specific captcha solution" }, - captcha_token: %Schema{type: :string, description: "Provider-specific captcha token"}, - captcha_answer_data: %Schema{type: :string, description: "Provider-specific captcha data"}, + captcha_token: %Schema{ + type: :string, + nullable: true, + description: "Provider-specific captcha token" + }, + captcha_answer_data: %Schema{ + type: :string, + nullable: true, + description: "Provider-specific captcha data" + }, token: %Schema{ type: :string, + nullable: true, description: "Invite token required when the registrations aren't public" } }, - required: [:username, :password, :agreement], example: %{ "username" => "cofe", "email" => "cofe@example.com", @@ -447,28 +460,34 @@ defmodule Pleroma.Web.ApiSpec.AccountOperation do properties: %{ bot: %Schema{ type: :boolean, + nullable: true, description: "Whether the account has a bot flag." }, display_name: %Schema{ type: :string, + nullable: true, description: "The display name to use for the profile." }, note: %Schema{type: :string, description: "The account bio."}, avatar: %Schema{ type: :string, + nullable: true, description: "Avatar image encoded using multipart/form-data", format: :binary }, header: %Schema{ type: :string, + nullable: true, description: "Header image encoded using multipart/form-data", format: :binary }, locked: %Schema{ type: :boolean, + nullable: true, description: "Whether manual approval of follow requests is required." }, fields_attributes: %Schema{ + nullable: true, oneOf: [ %Schema{type: :array, items: attribute_field()}, %Schema{type: :object, additionalProperties: %Schema{type: attribute_field()}} @@ -488,47 +507,65 @@ defmodule Pleroma.Web.ApiSpec.AccountOperation do # Pleroma-specific fields no_rich_text: %Schema{ type: :boolean, + nullable: true, description: "html tags are stripped from all statuses requested from the API" }, - hide_followers: %Schema{type: :boolean, description: "user's followers will be hidden"}, - hide_follows: %Schema{type: :boolean, description: "user's follows will be hidden"}, + hide_followers: %Schema{ + type: :boolean, + nullable: true, + description: "user's followers will be hidden" + }, + hide_follows: %Schema{ + type: :boolean, + nullable: true, + description: "user's follows will be hidden" + }, hide_followers_count: %Schema{ type: :boolean, + nullable: true, description: "user's follower count will be hidden" }, hide_follows_count: %Schema{ type: :boolean, + nullable: true, description: "user's follow count will be hidden" }, hide_favorites: %Schema{ type: :boolean, + nullable: true, description: "user's favorites timeline will be hidden" }, show_role: %Schema{ type: :boolean, + nullable: true, description: "user's role (e.g admin, moderator) will be exposed to anyone in the API" }, default_scope: VisibilityScope, pleroma_settings_store: %Schema{ type: :object, + nullable: true, description: "Opaque user settings to be saved on the backend." }, skip_thread_containment: %Schema{ type: :boolean, + nullable: true, description: "Skip filtering out broken threads" }, allow_following_move: %Schema{ type: :boolean, + nullable: true, description: "Allows automatically follow moved following accounts" }, pleroma_background_image: %Schema{ type: :string, + nullable: true, description: "Sets the background image of the user.", format: :binary }, discoverable: %Schema{ type: :boolean, + nullable: true, description: "Discovery of this account in search results and other services is allowed." }, @@ -624,7 +661,7 @@ defmodule Pleroma.Web.ApiSpec.AccountOperation do description: "POST body for muting an account", type: :object, properties: %{ - uri: %Schema{type: :string, format: :uri} + uri: %Schema{type: :string, nullable: true, format: :uri} }, required: [:uri] } @@ -638,6 +675,7 @@ defmodule Pleroma.Web.ApiSpec.AccountOperation do properties: %{ notifications: %Schema{ type: :boolean, + nullable: true, description: "Mute notifications in addition to statuses? Defaults to true.", default: true } diff --git a/lib/pleroma/web/api_spec/operations/app_operation.ex b/lib/pleroma/web/api_spec/operations/app_operation.ex index f6ccd073f..ae01cbbec 100644 --- a/lib/pleroma/web/api_spec/operations/app_operation.ex +++ b/lib/pleroma/web/api_spec/operations/app_operation.ex @@ -105,7 +105,11 @@ defmodule Pleroma.Web.ApiSpec.AppOperation do description: "Space separated list of scopes", default: "read" }, - website: %Schema{type: :string, description: "A URL to the homepage of your app"} + website: %Schema{ + type: :string, + nullable: true, + description: "A URL to the homepage of your app" + } }, required: [:client_name, :redirect_uris], example: %{ diff --git a/lib/pleroma/web/api_spec/operations/filter_operation.ex b/lib/pleroma/web/api_spec/operations/filter_operation.ex index 53e57b46b..7310c1c4d 100644 --- a/lib/pleroma/web/api_spec/operations/filter_operation.ex +++ b/lib/pleroma/web/api_spec/operations/filter_operation.ex @@ -199,12 +199,14 @@ defmodule Pleroma.Web.ApiSpec.FilterOperation do "Array of enumerable strings `home`, `notifications`, `public`, `thread`. At least one context must be specified." }, irreversible: %Schema{ - type: :bolean, + type: :boolean, + nullable: true, description: "Should the server irreversibly drop matching entities from home and notifications?" }, whole_word: %Schema{ - type: :bolean, + type: :boolean, + nullable: true, description: "Consider word boundaries?", default: true } diff --git a/lib/pleroma/web/api_spec/operations/marker_operation.ex b/lib/pleroma/web/api_spec/operations/marker_operation.ex index 06620492a..714ef1f99 100644 --- a/lib/pleroma/web/api_spec/operations/marker_operation.ex +++ b/lib/pleroma/web/api_spec/operations/marker_operation.ex @@ -110,14 +110,16 @@ defmodule Pleroma.Web.ApiSpec.MarkerOperation do properties: %{ notifications: %Schema{ type: :object, + nullable: true, properties: %{ - last_read_id: %Schema{type: :string} + last_read_id: %Schema{nullable: true, type: :string} } }, home: %Schema{ type: :object, + nullable: true, properties: %{ - last_read_id: %Schema{type: :string} + last_read_id: %Schema{nullable: true, type: :string} } } }, diff --git a/lib/pleroma/web/api_spec/operations/pleroma_account_operation.ex b/lib/pleroma/web/api_spec/operations/pleroma_account_operation.ex index 435991037..90922c064 100644 --- a/lib/pleroma/web/api_spec/operations/pleroma_account_operation.ex +++ b/lib/pleroma/web/api_spec/operations/pleroma_account_operation.ex @@ -143,6 +143,7 @@ defmodule Pleroma.Web.ApiSpec.PleromaAccountOperation do type: :object, properties: %{ img: %Schema{ + nullable: true, type: :string, format: :binary, description: "Image encoded using `multipart/form-data` or an empty string to clear" @@ -158,6 +159,7 @@ defmodule Pleroma.Web.ApiSpec.PleromaAccountOperation do properties: %{ banner: %Schema{ type: :string, + nullable: true, format: :binary, description: "Image encoded using `multipart/form-data` or an empty string to clear" } diff --git a/lib/pleroma/web/api_spec/operations/report_operation.ex b/lib/pleroma/web/api_spec/operations/report_operation.ex index da4d50703..882177c96 100644 --- a/lib/pleroma/web/api_spec/operations/report_operation.ex +++ b/lib/pleroma/web/api_spec/operations/report_operation.ex @@ -37,15 +37,18 @@ defmodule Pleroma.Web.ApiSpec.ReportOperation do account_id: %Schema{type: :string, description: "ID of the account to report"}, status_ids: %Schema{ type: :array, + nullable: true, items: %Schema{type: :string}, description: "Array of Statuses to attach to the report, for context" }, comment: %Schema{ type: :string, + nullable: true, description: "Reason for the report" }, forward: %Schema{ type: :boolean, + nullable: true, default: false, description: "If the account is remote, should the report be forwarded to the remote admin?" diff --git a/lib/pleroma/web/api_spec/operations/status_operation.ex b/lib/pleroma/web/api_spec/operations/status_operation.ex index 561db3bce..fc2909d8c 100644 --- a/lib/pleroma/web/api_spec/operations/status_operation.ex +++ b/lib/pleroma/web/api_spec/operations/status_operation.ex @@ -371,15 +371,18 @@ defmodule Pleroma.Web.ApiSpec.StatusOperation do properties: %{ status: %Schema{ type: :string, + nullable: true, description: "Text content of the status. If `media_ids` is provided, this becomes optional. Attaching a `poll` is optional while `status` is provided." }, media_ids: %Schema{ + nullable: true, type: :array, items: %Schema{type: :string}, description: "Array of Attachment ids to be attached as media." }, poll: %Schema{ + nullable: true, type: :object, required: [:options], properties: %{ @@ -390,26 +393,35 @@ defmodule Pleroma.Web.ApiSpec.StatusOperation do }, expires_in: %Schema{ type: :integer, + nullable: true, description: "Duration the poll should be open, in seconds. Must be provided with `poll[options]`" }, - multiple: %Schema{type: :boolean, description: "Allow multiple choices?"}, + multiple: %Schema{ + type: :boolean, + nullable: true, + description: "Allow multiple choices?" + }, hide_totals: %Schema{ type: :boolean, + nullable: true, description: "Hide vote counts until the poll ends?" } } }, in_reply_to_id: %Schema{ + nullable: true, allOf: [FlakeID], description: "ID of the status being replied to, if status is a reply" }, sensitive: %Schema{ type: :boolean, + nullable: true, description: "Mark status and attached media as sensitive?" }, spoiler_text: %Schema{ type: :string, + nullable: true, description: "Text to be shown as a warning or subject before the actual content. Statuses are generally collapsed behind this field." }, @@ -420,25 +432,33 @@ defmodule Pleroma.Web.ApiSpec.StatusOperation do description: "ISO 8601 Datetime at which to schedule a status. Providing this paramter will cause ScheduledStatus to be returned instead of Status. Must be at least 5 minutes in the future." }, - language: %Schema{type: :string, description: "ISO 639 language code for this status."}, + language: %Schema{ + type: :string, + nullable: true, + description: "ISO 639 language code for this status." + }, # Pleroma-specific properties: preview: %Schema{ type: :boolean, + nullable: true, description: "If set to `true` the post won't be actually posted, but the status entitiy would still be rendered back. This could be useful for previewing rich text/custom emoji, for example" }, content_type: %Schema{ type: :string, + nullable: true, description: "The MIME type of the status, it is transformed into HTML by the backend. You can get the list of the supported MIME types with the nodeinfo endpoint." }, to: %Schema{ type: :array, + nullable: true, items: %Schema{type: :string}, description: "A list of nicknames (like `lain@soykaf.club` or `lain` on the local server) that will be used to determine who is going to be addressed by this post. Using this will disable the implicit addressing by mentioned names in the `status` body, only the people in the `to` list will be addressed. The normal rules for for post visibility are not affected by this and will still apply" }, visibility: %Schema{ + nullable: true, anyOf: [ VisibilityScope, %Schema{type: :string, description: "`list:LIST_ID`", example: "LIST:123"} @@ -447,11 +467,13 @@ defmodule Pleroma.Web.ApiSpec.StatusOperation do "Visibility of the posted status. Besides standard MastoAPI values (`direct`, `private`, `unlisted` or `public`) it can be used to address a List by setting it to `list:LIST_ID`" }, expires_in: %Schema{ + nullable: true, type: :integer, description: "The number of seconds the posted activity should expire in. When a posted activity expires it will be deleted from the server, and a delete request for it will be federated. This needs to be longer than an hour." }, in_reply_to_conversation_id: %Schema{ + nullable: true, type: :string, description: "Will reply to a given conversation, addressing only the people who are part of the recipient set of that conversation. Sets the visibility to `direct`." diff --git a/lib/pleroma/web/api_spec/operations/subscription_operation.ex b/lib/pleroma/web/api_spec/operations/subscription_operation.ex index 663b8fa11..cf6dcb068 100644 --- a/lib/pleroma/web/api_spec/operations/subscription_operation.ex +++ b/lib/pleroma/web/api_spec/operations/subscription_operation.ex @@ -109,19 +109,38 @@ defmodule Pleroma.Web.ApiSpec.SubscriptionOperation do required: [:endpoint, :keys] }, data: %Schema{ + nullable: true, type: :object, properties: %{ alerts: %Schema{ + nullable: true, type: :object, properties: %{ - follow: %Schema{type: :boolean, description: "Receive follow notifications?"}, + follow: %Schema{ + type: :boolean, + nullable: true, + description: "Receive follow notifications?" + }, favourite: %Schema{ type: :boolean, + nullable: true, description: "Receive favourite notifications?" }, - reblog: %Schema{type: :boolean, description: "Receive reblog notifications?"}, - mention: %Schema{type: :boolean, description: "Receive mention notifications?"}, - poll: %Schema{type: :boolean, description: "Receive poll notifications?"} + reblog: %Schema{ + type: :boolean, + nullable: true, + description: "Receive reblog notifications?" + }, + mention: %Schema{ + type: :boolean, + nullable: true, + description: "Receive mention notifications?" + }, + poll: %Schema{ + type: :boolean, + nullable: true, + description: "Receive poll notifications?" + } } } } @@ -154,19 +173,38 @@ defmodule Pleroma.Web.ApiSpec.SubscriptionOperation do type: :object, properties: %{ data: %Schema{ + nullable: true, type: :object, properties: %{ alerts: %Schema{ + nullable: true, type: :object, properties: %{ - follow: %Schema{type: :boolean, description: "Receive follow notifications?"}, + follow: %Schema{ + type: :boolean, + nullable: true, + description: "Receive follow notifications?" + }, favourite: %Schema{ type: :boolean, + nullable: true, description: "Receive favourite notifications?" }, - reblog: %Schema{type: :boolean, description: "Receive reblog notifications?"}, - mention: %Schema{type: :boolean, description: "Receive mention notifications?"}, - poll: %Schema{type: :boolean, description: "Receive poll notifications?"} + reblog: %Schema{ + type: :boolean, + nullable: true, + description: "Receive reblog notifications?" + }, + mention: %Schema{ + type: :boolean, + nullable: true, + description: "Receive mention notifications?" + }, + poll: %Schema{ + type: :boolean, + nullable: true, + description: "Receive poll notifications?" + } } } }