From 4511de98ea636d87969531b40c07f1ef5fd25f20 Mon Sep 17 00:00:00 2001 From: bakaneko Date: Tue, 13 Aug 2024 06:51:21 +0900 Subject: [PATCH 01/25] missing urlParams for ChannelsController --- app/Http/Controllers/Chat/ChannelsController.php | 13 +++++++++++-- 1 file changed, 11 insertions(+), 2 deletions(-) diff --git a/app/Http/Controllers/Chat/ChannelsController.php b/app/Http/Controllers/Chat/ChannelsController.php index 372acccd2f9..f6b0ad143f2 100644 --- a/app/Http/Controllers/Chat/ChannelsController.php +++ b/app/Http/Controllers/Chat/ChannelsController.php @@ -67,6 +67,9 @@ public function index() * * Returns the joined [ChatChannel](#chatchannel). * + * @urlParam channel integer required The `channel_id` of the [ChatChannel](#chatchannel) to mark as read. + * @urlParam message integer required The `message_id` of the [ChatMessage](#chatmessage) to mark as read up to. + * * @response { * "channel_id": 5, * "current_user_attributes": { @@ -113,6 +116,9 @@ public function join($channelId, $userId) * This endpoint will only allow the leaving of public channels initially. * * + * @urlParam channel integer required `channel_id` of the [ChatChannel](#chatchannel) leave. + * @urlParam user integer required `id` of the [User](#user) to leave the channel. + * * @response 204 */ public function part($channelId, $userId) @@ -146,6 +152,8 @@ public function part($channelId, $userId) * channel | [ChatChannel](#chatchannel) | | * users | [User](#user) | Users are only visible for PM channels. * + * @urlParam channel integer required `channel_id` of the [ChatChannel](#chatchannel) to get. + * * @response { * "channel": { * "channel_id": 1337, @@ -191,6 +199,7 @@ public function part($channelId, $userId) * } * ] * } + * */ public function show($channelId) { @@ -314,8 +323,8 @@ public function store() * Note that the read marker cannot be moved backwards - i.e. if a channel has been marked as read up to message_id = 12, you cannot then set it backwards to message_id = 10. It will be rejected. * * - * @queryParam channel_id required The `channel_id` of the channel to mark as read - * @queryParam message_id required The `message_id` of the message to mark as read up to + * @urlParam channel integer required The `channel_id` of the [ChatChannel](#chatchannel) to mark as read. + * @urlParam message integer required The `message_id` of the [ChatMessage](#chatmessage) to mark as read up to. * * @response 204 */ From 87ded8167ed401bca4097a74cfda20677bfb0af0 Mon Sep 17 00:00:00 2001 From: bakaneko Date: Tue, 13 Aug 2024 08:25:20 +0900 Subject: [PATCH 02/25] missing param types on BeatmapsController --- app/Http/Controllers/BeatmapsController.php | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/app/Http/Controllers/BeatmapsController.php b/app/Http/Controllers/BeatmapsController.php index 33b76791953..104c2d7e784 100644 --- a/app/Http/Controllers/BeatmapsController.php +++ b/app/Http/Controllers/BeatmapsController.php @@ -241,9 +241,9 @@ public function index() * * See [Get Beatmap](#get-beatmap) * - * @queryParam checksum A beatmap checksum. - * @queryParam filename A filename to lookup. - * @queryParam id A beatmap ID to lookup. + * @queryParam checksum string A beatmap checksum. + * @queryParam filename string A filename to lookup. + * @queryParam id integer A beatmap ID to lookup. * * @response "See Beatmap object section" */ @@ -343,7 +343,7 @@ public function show($id) * * @queryParam legacy_only integer Whether or not to exclude lazer scores. Defaults to 0. Example: 0 * @queryParam mode The [Ruleset](#ruleset) to get scores for. - * @queryParam mods An array of matching Mods, or none // TODO. + * @queryParam mods string[] An array of matching Mods, or none // TODO. * @queryParam type Beatmap score ranking type // TODO. */ public function scores($id) @@ -370,7 +370,7 @@ public function scores($id) * @urlParam beatmap integer required Id of the [Beatmap](#beatmap). * * @queryParam mode The [Ruleset](#ruleset) to get scores for. - * @queryParam mods An array of matching Mods, or none // TODO. + * @queryParam mods string[] An array of matching Mods, or none // TODO. * @queryParam type Beatmap score ranking type // TODO. */ public function soloScores($id) From 115511b59bd8997637df5fabfc1efe177d67f576 Mon Sep 17 00:00:00 2001 From: bakaneko Date: Tue, 13 Aug 2024 08:32:23 +0900 Subject: [PATCH 03/25] missing params for BeatmapDiscussionPostsController --- .../BeatmapDiscussionPostsController.php | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/app/Http/Controllers/BeatmapDiscussionPostsController.php b/app/Http/Controllers/BeatmapDiscussionPostsController.php index f02f81f125c..f86a16d5e4c 100644 --- a/app/Http/Controllers/BeatmapDiscussionPostsController.php +++ b/app/Http/Controllers/BeatmapDiscussionPostsController.php @@ -63,13 +63,14 @@ public function destroy($id) * posts | [BeatmapsetDiscussionPost](#beatmapsetdiscussionpost)[] | | * users | [User](#user) | | * - * @queryParam beatmapset_discussion_id `id` of the [BeatmapsetDiscussion](#beatmapsetdiscussion). - * @queryParam limit Maximum number of results. - * @queryParam page Search result page. - * @queryParam sort `id_desc` for newest first; `id_asc` for oldest first. Defaults to `id_desc`. - * @queryParam types[] `first`, `reply`, `system` are the valid values. Defaults to `reply`. - * @queryParam user The `id` of the [User](#user). - * @queryParam with_deleted This param has no effect as api calls do not currently receive group permissions. + * @usesCursor + * @queryParam beatmapset_discussion_id integer `id` of the [BeatmapsetDiscussion](#beatmapsetdiscussion). + * @queryParam limit integer Maximum number of results. + * @queryParam page integer Search result page. + * @queryParam sort string `id_desc` for newest first; `id_asc` for oldest first. Defaults to `id_desc`. + * @queryParam types string[] `first`, `reply`, `system` are the valid values. Defaults to `reply`. + * @queryParam user integer The `id` of the [User](#user). + * @queryParam with_deleted integer This param has no effect as api calls do not currently receive group permissions. */ public function index() { From bd49f64bcad6790bd419afa0caa0e48df1254bb8 Mon Sep 17 00:00:00 2001 From: bakaneko Date: Tue, 13 Aug 2024 09:04:23 +0900 Subject: [PATCH 04/25] missing param types for BeatmapsetDiscussionVotesController --- .../BeatmapsetDiscussionVotesController.php | 17 +++++++++-------- 1 file changed, 9 insertions(+), 8 deletions(-) diff --git a/app/Http/Controllers/BeatmapsetDiscussionVotesController.php b/app/Http/Controllers/BeatmapsetDiscussionVotesController.php index 7181060db3a..48d256dab3c 100644 --- a/app/Http/Controllers/BeatmapsetDiscussionVotesController.php +++ b/app/Http/Controllers/BeatmapsetDiscussionVotesController.php @@ -39,14 +39,15 @@ public function __construct() * users | [User](#user) | | * votes | [BeatmapsetDiscussionVote](#beatmapsetdiscussionvote)[] | | * - * @queryParam beatmapset_discussion_id `id` of the [BeatmapsetDiscussion](#beatmapsetdiscussion). - * @queryParam limit Maximum number of results. - * @queryParam page Search result page. - * @queryParam receiver The `id` of the [User](#user) receiving the votes. - * @queryParam score `1` for up vote, `-1` for down vote. - * @queryParam sort `id_desc` for newest first; `id_asc` for oldest first. Defaults to `id_desc`. - * @queryParam user The `id` of the [User](#user) giving the votes. - * @queryParam with_deleted This param has no effect as api calls do not currently receive group permissions. + * @usesCursor + * @queryParam beatmapset_discussion_id integer `id` of the [BeatmapsetDiscussion](#beatmapsetdiscussion). + * @queryParam limit integer Maximum number of results. + * @queryParam page integer Search result page. + * @queryParam receiver integer The `id` of the [User](#user) receiving the votes. + * @queryParam score integer `1` for up vote, `-1` for down vote. + * @queryParam sort string `id_desc` for newest first; `id_asc` for oldest first. Defaults to `id_desc`. + * @queryParam user integer The `id` of the [User](#user) giving the votes. + * @queryParam with_deleted integer This param has no effect as api calls do not currently receive group permissions. */ public function index() { From 50527d076baee513735518dcdd962f666d257ac6 Mon Sep 17 00:00:00 2001 From: bakaneko Date: Tue, 13 Aug 2024 09:13:25 +0900 Subject: [PATCH 05/25] missing param types for BeatmapDiscussionsController --- .../BeatmapDiscussionsController.php | 20 +++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/app/Http/Controllers/BeatmapDiscussionsController.php b/app/Http/Controllers/BeatmapDiscussionsController.php index ecc1e30e2fe..f97f07166c2 100644 --- a/app/Http/Controllers/BeatmapDiscussionsController.php +++ b/app/Http/Controllers/BeatmapDiscussionsController.php @@ -90,16 +90,16 @@ public function destroy($id) * users | [User](#user)[] | List of users associated with the discussions returned. * * @usesCursor - * @queryParam beatmap_id `id` of the [Beatmap](#beatmap). - * @queryParam beatmapset_id `id` of the [Beatmapset](#beatmapset). - * @queryParam beatmapset_status One of `all`, `ranked`, `qualified`, `disqualified`, `never_qualified`. Defaults to `all`. TODO: better descriptions. - * @queryParam limit Maximum number of results. - * @queryParam message_types[] `suggestion`, `problem`, `mapper_note`, `praise`, `hype`, `review`. Blank defaults to all types. TODO: better descriptions. - * @queryParam only_unresolved `true` to show only unresolved issues; `false`, otherwise. Defaults to `false`. - * @queryParam page Search result page. - * @queryParam sort `id_desc` for newest first; `id_asc` for oldest first. Defaults to `id_desc`. - * @queryParam user The `id` of the [User](#user). - * @queryParam with_deleted This param has no effect as api calls do not currently receive group permissions. + * @queryParam beatmap_id integer `id` of the [Beatmap](#beatmap). + * @queryParam beatmapset_id integer `id` of the [Beatmapset](#beatmapset). + * @queryParam beatmapset_status string One of `all`, `ranked`, `qualified`, `disqualified`, `never_qualified`. Defaults to `all`. TODO: better descriptions. + * @queryParam limit integer Maximum number of results. + * @queryParam message_types string[] `suggestion`, `problem`, `mapper_note`, `praise`, `hype`, `review`. Blank defaults to all types. TODO: better descriptions. + * @queryParam only_unresolved boolean `true` to show only unresolved issues; `false`, otherwise. Defaults to `false`. + * @queryParam page integer Search result page. + * @queryParam sort string `id_desc` for newest first; `id_asc` for oldest first. Defaults to `id_desc`. + * @queryParam user integer The `id` of the [User](#user). + * @queryParam with_deleted integer This param has no effect as api calls do not currently receive group permissions. */ public function index() { From 1362cca29a87b4f62b91a6cc292b4dc23ae6070a Mon Sep 17 00:00:00 2001 From: bakaneko Date: Tue, 13 Aug 2024 10:25:58 +0900 Subject: [PATCH 06/25] array on type not param --- app/Http/Controllers/ChangelogController.php | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/app/Http/Controllers/ChangelogController.php b/app/Http/Controllers/ChangelogController.php index 058e09501cd..983f96c218c 100644 --- a/app/Http/Controllers/ChangelogController.php +++ b/app/Http/Controllers/ChangelogController.php @@ -244,7 +244,7 @@ public function github() * * @urlParam changelog string required Build version, update stream name, or build ID. Example: 20210520.2 * @queryParam key string Unset to query by build version or stream name, or `id` to query by build ID. No-example - * @queryParam message_formats[] string `html`, `markdown`. Default to both. + * @queryParam message_formats string[] `html`, `markdown`. Default to both. * @response See "Get Changelog Build" response. */ public function show($version) From f05998d301e01c3514c37f9861754fe524bd56b8 Mon Sep 17 00:00:00 2001 From: bakaneko Date: Tue, 13 Aug 2024 12:12:33 +0900 Subject: [PATCH 07/25] missing param types for CommentsController --- app/Http/Controllers/CommentsController.php | 29 ++++++++++++++------- 1 file changed, 19 insertions(+), 10 deletions(-) diff --git a/app/Http/Controllers/CommentsController.php b/app/Http/Controllers/CommentsController.php index a85024632c9..ff70c363497 100644 --- a/app/Http/Controllers/CommentsController.php +++ b/app/Http/Controllers/CommentsController.php @@ -38,6 +38,8 @@ public function __construct() * ### Response Format * * Returns [CommentBundle](#commentbundle) + * + * @urlParam comment integer required The `id` of the [Comment](#comment) */ public function destroy($id) { @@ -67,12 +69,12 @@ public function destroy($id) * * `pinned_comments` is only included when `commentable_type` and `commentable_id` are specified. * - * @queryParam after Return comments which come after the specified comment id as per sort option. No-example - * @queryParam commentable_type The type of resource to get comments for. Example: beatmapset - * @queryParam commentable_id The id of the resource to get comments for. Example: 1 + * @queryParam after integer Return comments which come after the specified comment id as per sort option. No-example + * @queryParam commentable_type string The type of resource to get comments for. Example: beatmapset + * @queryParam commentable_id integer The id of the resource to get comments for. Example: 1 * @queryParam cursor Pagination option. See [CommentSort](#commentsort) for detail. The format follows [Cursor](#cursor) except it's not currently included in the response. No-example - * @queryParam parent_id Limit to comments which are reply to the specified id. Specify 0 to get top level comments. Example: 1 - * @queryParam sort Sort option as defined in [CommentSort](#commentsort). Defaults to `new` for guests and user-specified default when authenticated. Example: new + * @queryParam parent_id integer Limit to comments which are reply to the specified id. Specify 0 to get top level comments. Example: 1 + * @queryParam sort string Sort option as defined in [CommentSort](#commentsort). Defaults to `new` for guests and user-specified default when authenticated. Example: new */ public function index() { @@ -150,6 +152,8 @@ public function restore($id) * ### Response Format * * Returns [CommentBundle](#commentbundle) + * + * @urlParam comment integer required The `id` of the [Comment](#comment) */ public function show($id) { @@ -177,10 +181,10 @@ public function show($id) * * Returns [CommentBundle](#commentbundle) * - * @queryParam comment.commentable_id Resource ID the comment thread is attached to - * @queryParam comment.commentable_type Resource type the comment thread is attached to - * @queryParam comment.message Text of the comment - * @queryParam comment.parent_id The id of the comment to reply to, null if not a reply + * @queryParam comment.commentable_id integer required Resource ID the comment thread is attached to + * @queryParam comment.commentable_type string required Resource type the comment thread is attached to + * @queryParam comment.message string required Text of the comment + * @queryParam comment.parent_id integer The id of the comment to reply to, null if not a reply */ public function store() { @@ -225,7 +229,8 @@ public function store() * * Returns [CommentBundle](#commentbundle) * - * @queryParam comment.message New text of the comment + * @urlParam comment integer required The `id` of the [Comment](#comment) + * @queryParam comment.message string required New text of the comment */ public function update($id) { @@ -277,6 +282,8 @@ public function pinStore($id) * ### Response Format * * Returns [CommentBundle](#commentbundle) + * + * @urlParam comment integer required The `id` of the [Comment](#comment) */ public function voteDestroy($id) { @@ -303,6 +310,8 @@ public function voteDestroy($id) * ### Response Format * * Returns [CommentBundle](#commentbundle) + * + * @urlParam comment integer required The `id` of the [Comment](#comment) */ public function voteStore($id) { From 6da604988e552d636edead89b13b77d7209a5337 Mon Sep 17 00:00:00 2001 From: bakaneko Date: Tue, 13 Aug 2024 17:58:04 +0900 Subject: [PATCH 08/25] missing required --- app/Http/Controllers/Forum/TopicsController.php | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/app/Http/Controllers/Forum/TopicsController.php b/app/Http/Controllers/Forum/TopicsController.php index d8c4e34b628..a98bf428698 100644 --- a/app/Http/Controllers/Forum/TopicsController.php +++ b/app/Http/Controllers/Forum/TopicsController.php @@ -558,7 +558,7 @@ public function store() * The edited [ForumTopic](#forum-topic). * * @urlParam topic integer required Id of the topic. Example: 1 - * @bodyParam forum_topic[topic_title] string New topic title. Example: titled + * @bodyParam forum_topic[topic_title] string required New topic title. Example: titled */ public function update($id) { From 143b6d5d741a33ddda5bd034dcabb1bbcfc78745 Mon Sep 17 00:00:00 2001 From: bakaneko Date: Tue, 13 Aug 2024 17:58:41 +0900 Subject: [PATCH 09/25] correct link --- resources/views/docs/_websocket_events.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/resources/views/docs/_websocket_events.md b/resources/views/docs/_websocket_events.md index c0edb63d259..9b1aaa24c0a 100644 --- a/resources/views/docs/_websocket_events.md +++ b/resources/views/docs/_websocket_events.md @@ -48,7 +48,7 @@ Broadcast to the user when the user joins a chat channel. ### Payload Format -[ChatChannel](#chat-channel) with `current_user_attributes`, `last_message_id`, `users` additional attributes. +[ChatChannel](#chatchannel) with `current_user_attributes`, `last_message_id`, `users` additional attributes. ## chat.channel.part @@ -56,7 +56,7 @@ Broadcast to the user when the user leaves a chat channel. ### Payload Format -[ChatChannel](#chat-channel) with `current_user_attributes`, `last_message_id`, `users` additional attributes. +[ChatChannel](#chatchannel) with `current_user_attributes`, `last_message_id`, `users` additional attributes. ## chat.message.new From 9784473716709dfdfc95781cfd87ef57d7c3bab5 Mon Sep 17 00:00:00 2001 From: bakaneko Date: Tue, 13 Aug 2024 18:03:39 +0900 Subject: [PATCH 10/25] missing param type on NotificationsController --- app/Http/Controllers/NotificationsController.php | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/app/Http/Controllers/NotificationsController.php b/app/Http/Controllers/NotificationsController.php index b65192d69e0..b0b79b5cb91 100644 --- a/app/Http/Controllers/NotificationsController.php +++ b/app/Http/Controllers/NotificationsController.php @@ -56,7 +56,7 @@ public function endpoint() * unread_count | total unread notifications * notification_endpoint | url to connect to websocket server * - * @queryParam max_id Maximum `id` fetched. Can be used to load earlier notifications. Defaults to no limit (fetch latest notifications) + * @queryParam max_id integer Maximum `id` fetched. Can be used to load earlier notifications. Defaults to no limit (fetch latest notifications). No-example * * @response { * "has_more": true, From 937b0adcf3fbae0021663fe55b2e0515027fd104 Mon Sep 17 00:00:00 2001 From: bakaneko Date: Tue, 13 Aug 2024 18:11:58 +0900 Subject: [PATCH 11/25] missing params types on RankingsController --- app/Http/Controllers/RankingController.php | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/app/Http/Controllers/RankingController.php b/app/Http/Controllers/RankingController.php index 51980dc82d8..8adfcb5ab69 100644 --- a/app/Http/Controllers/RankingController.php +++ b/app/Http/Controllers/RankingController.php @@ -151,10 +151,10 @@ public static function url( * @urlParam type string required [RankingType](#rankingtype). Example: performance * * @queryParam country string Filter ranking by country code. Only available for `type` of `performance`. Example: JP - * @queryParam cursor [Cursor](#cursor). No-example - * @queryParam filter Either `all` (default) or `friends`. Example: all - * @queryParam spotlight The id of the spotlight if `type` is `charts`. Ranking for latest spotlight will be returned if not specified. No-example - * @queryParam variant Filter ranking to specified mode variant. For `mode` of `mania`, it's either `4k` or `7k`. Only available for `type` of `performance`. Example: 4k + * @queryParam cursor.page integer See [Cursor](#cursor). No-example + * @queryParam filter string Either `all` (default) or `friends`. Example: all + * @queryParam spotlight integer The id of the spotlight if `type` is `charts`. Ranking for latest spotlight will be returned if not specified. No-example + * @queryParam variant string Filter ranking to specified mode variant. For `mode` of `mania`, it's either `4k` or `7k`. Only available for `type` of `performance`. Example: 4k */ public function index($mode, $type) { From 9bdd06857ed21c15eb9ec3b233fa9a54ff7d262d Mon Sep 17 00:00:00 2001 From: bakaneko Date: Tue, 13 Aug 2024 19:18:38 +0900 Subject: [PATCH 12/25] missing param types + fixes for UsersController --- app/Http/Controllers/UsersController.php | 16 ++++++---------- 1 file changed, 6 insertions(+), 10 deletions(-) diff --git a/app/Http/Controllers/UsersController.php b/app/Http/Controllers/UsersController.php index cd72c10642a..3c5512c29ae 100644 --- a/app/Http/Controllers/UsersController.php +++ b/app/Http/Controllers/UsersController.php @@ -332,7 +332,7 @@ public function beatmapsets($_userId, $type) * ----- | --------------- | ----------- * users | [User](#user)[] | Includes `country`, `cover`, `groups`, and `statistics_rulesets`. * - * @queryParam ids[] User id to be returned. Specify once for each user id requested. Up to 50 users can be requested at once. Example: 1 + * @queryParam ids integer[] `id`s of users to be returned. Specify once for each user id requested. Up to 50 users can be requested at once. Example: [1,2] * @queryParam include_variant_statistics boolean Whether to additionally include `statistics_rulesets.variants` (default: `false`). No-example * * @response { @@ -503,10 +503,10 @@ public function recentActivity($_userId) * @urlParam type string required Score type. Must be one of these: `best`, `firsts`, `recent`. Example: best * * @queryParam legacy_only integer Whether or not to exclude lazer scores. Defaults to 0. Example: 0 - * @queryParam include_fails Only for recent scores, include scores of failed plays. Set to 1 to include them. Defaults to 0. Example: 0 - * @queryParam mode [Ruleset](#ruleset) of the scores to be returned. Defaults to the specified `user`'s mode. Example: osu - * @queryParam limit Maximum number of results. - * @queryParam offset Result offset for pagination. Example: 1 + * @queryParam include_fails integer Only for recent scores, include scores of failed plays. Set to 1 to include them. Defaults to 0. Example: 0 + * @queryParam mode string [Ruleset](#ruleset) of the scores to be returned. Defaults to the specified `user`'s mode. Example: osu + * @queryParam limit integer Maximum number of results. + * @queryParam offset integer Result offset for pagination. Example: 1 * * @response [ * { @@ -594,10 +594,6 @@ public function me($mode = null) * * This endpoint returns the detail of specified user. * - * - * * --- * * ### Response format @@ -636,7 +632,7 @@ public function me($mode = null) * @urlParam user integer required Id or `@`-prefixed username of the user. Previous usernames are also checked in some cases. Example: 1 * @urlParam mode string [Ruleset](#ruleset). User default mode will be used if not specified. Example: osu * - * @queryParam key Type of `user` passed in url parameter. Can be either `id` or `username` to limit lookup by their respective type. Passing empty or invalid value will result in id lookup followed by username lookup if not found. This parameter has been deprecated. Prefix `user` parameter with `@` instead to lookup by username. + * @queryParam key string Type of `user` passed in url parameter. Can be either `id` or `username` to limit lookup by their respective type. Passing empty or invalid value will result in id lookup followed by username lookup if not found. This parameter has been deprecated. Prefix `user` parameter with `@` instead to lookup by username. No-example * * @response "See User object section" */ From b02d4b484844a5c3ef00751052a417e9d4d38559 Mon Sep 17 00:00:00 2001 From: bakaneko Date: Tue, 13 Aug 2024 19:31:15 +0900 Subject: [PATCH 13/25] setting example/no-example --- .../BeatmapDiscussionPostsController.php | 2 +- .../BeatmapDiscussionsController.php | 8 ++++---- app/Http/Controllers/BeatmapsController.php | 20 +++++++++---------- .../BeatmapsetDiscussionVotesController.php | 10 +++++----- app/Http/Controllers/ChangelogController.php | 2 +- app/Http/Controllers/CommentsController.php | 6 +++--- 6 files changed, 24 insertions(+), 24 deletions(-) diff --git a/app/Http/Controllers/BeatmapDiscussionPostsController.php b/app/Http/Controllers/BeatmapDiscussionPostsController.php index f86a16d5e4c..9fdbc7a6dbc 100644 --- a/app/Http/Controllers/BeatmapDiscussionPostsController.php +++ b/app/Http/Controllers/BeatmapDiscussionPostsController.php @@ -70,7 +70,7 @@ public function destroy($id) * @queryParam sort string `id_desc` for newest first; `id_asc` for oldest first. Defaults to `id_desc`. * @queryParam types string[] `first`, `reply`, `system` are the valid values. Defaults to `reply`. * @queryParam user integer The `id` of the [User](#user). - * @queryParam with_deleted integer This param has no effect as api calls do not currently receive group permissions. + * @queryParam with_deleted boolean This param has no effect as api calls do not currently receive group permissions. */ public function index() { diff --git a/app/Http/Controllers/BeatmapDiscussionsController.php b/app/Http/Controllers/BeatmapDiscussionsController.php index f97f07166c2..750ebc4388d 100644 --- a/app/Http/Controllers/BeatmapDiscussionsController.php +++ b/app/Http/Controllers/BeatmapDiscussionsController.php @@ -92,14 +92,14 @@ public function destroy($id) * @usesCursor * @queryParam beatmap_id integer `id` of the [Beatmap](#beatmap). * @queryParam beatmapset_id integer `id` of the [Beatmapset](#beatmapset). - * @queryParam beatmapset_status string One of `all`, `ranked`, `qualified`, `disqualified`, `never_qualified`. Defaults to `all`. TODO: better descriptions. + * @queryParam beatmapset_status string One of `all`, `ranked`, `qualified`, `disqualified`, `never_qualified`. Defaults to `all`. TODO: better descriptions. No-example * @queryParam limit integer Maximum number of results. - * @queryParam message_types string[] `suggestion`, `problem`, `mapper_note`, `praise`, `hype`, `review`. Blank defaults to all types. TODO: better descriptions. + * @queryParam message_types string[] `suggestion`, `problem`, `mapper_note`, `praise`, `hype`, `review`. Blank defaults to all types. TODO: better descriptions. No-example * @queryParam only_unresolved boolean `true` to show only unresolved issues; `false`, otherwise. Defaults to `false`. * @queryParam page integer Search result page. - * @queryParam sort string `id_desc` for newest first; `id_asc` for oldest first. Defaults to `id_desc`. + * @queryParam sort string `id_desc` for newest first; `id_asc` for oldest first. Defaults to `id_desc`. No-example * @queryParam user integer The `id` of the [User](#user). - * @queryParam with_deleted integer This param has no effect as api calls do not currently receive group permissions. + * @queryParam with_deleted boolean This param has no effect as api calls do not currently receive group permissions. No-example */ public function index() { diff --git a/app/Http/Controllers/BeatmapsController.php b/app/Http/Controllers/BeatmapsController.php index 104c2d7e784..ebe9af70cb4 100644 --- a/app/Http/Controllers/BeatmapsController.php +++ b/app/Http/Controllers/BeatmapsController.php @@ -241,9 +241,9 @@ public function index() * * See [Get Beatmap](#get-beatmap) * - * @queryParam checksum string A beatmap checksum. - * @queryParam filename string A filename to lookup. - * @queryParam id integer A beatmap ID to lookup. + * @queryParam checksum string A beatmap checksum. No-example + * @queryParam filename string A filename to lookup. No-example + * @queryParam id integer A beatmap ID to lookup. No-example * * @response "See Beatmap object section" */ @@ -342,9 +342,9 @@ public function show($id) * @urlParam beatmap integer required Id of the [Beatmap](#beatmap). * * @queryParam legacy_only integer Whether or not to exclude lazer scores. Defaults to 0. Example: 0 - * @queryParam mode The [Ruleset](#ruleset) to get scores for. - * @queryParam mods string[] An array of matching Mods, or none // TODO. - * @queryParam type Beatmap score ranking type // TODO. + * @queryParam mode The [Ruleset](#ruleset) to get scores for. Example: osu + * @queryParam mods string[] An array of matching Mods, or none // TODO. No-example + * @queryParam type string Beatmap score ranking type // TODO. No-example */ public function scores($id) { @@ -369,9 +369,9 @@ public function scores($id) * * @urlParam beatmap integer required Id of the [Beatmap](#beatmap). * - * @queryParam mode The [Ruleset](#ruleset) to get scores for. + * @queryParam mode string The [Ruleset](#ruleset) to get scores for. Example: osu * @queryParam mods string[] An array of matching Mods, or none // TODO. - * @queryParam type Beatmap score ranking type // TODO. + * @queryParam type string Beatmap score ranking type // TODO. No-example */ public function soloScores($id) { @@ -422,8 +422,8 @@ public function updateOwner($id) * @urlParam user integer required Id of the [User](#user). * * @queryParam legacy_only integer Whether or not to exclude lazer scores. Defaults to 0. Example: 0 - * @queryParam mode The [Ruleset](#ruleset) to get scores for. - * @queryParam mods An array of matching Mods, or none // TODO. + * @queryParam mode string The [Ruleset](#ruleset) to get scores for. Example: osu + * @queryParam mods string[] An array of matching Mods, or none // TODO. No-example */ public function userScore($beatmapId, $userId) { diff --git a/app/Http/Controllers/BeatmapsetDiscussionVotesController.php b/app/Http/Controllers/BeatmapsetDiscussionVotesController.php index 48d256dab3c..7297230a905 100644 --- a/app/Http/Controllers/BeatmapsetDiscussionVotesController.php +++ b/app/Http/Controllers/BeatmapsetDiscussionVotesController.php @@ -41,13 +41,13 @@ public function __construct() * * @usesCursor * @queryParam beatmapset_discussion_id integer `id` of the [BeatmapsetDiscussion](#beatmapsetdiscussion). - * @queryParam limit integer Maximum number of results. - * @queryParam page integer Search result page. + * @queryParam limit integer Maximum number of results. No-example + * @queryParam page integer Search result page. No-example * @queryParam receiver integer The `id` of the [User](#user) receiving the votes. - * @queryParam score integer `1` for up vote, `-1` for down vote. - * @queryParam sort string `id_desc` for newest first; `id_asc` for oldest first. Defaults to `id_desc`. + * @queryParam score integer `1` for up vote, `-1` for down vote. Example: 1 + * @queryParam sort string `id_desc` for newest first; `id_asc` for oldest first. Defaults to `id_desc`. No-example * @queryParam user integer The `id` of the [User](#user) giving the votes. - * @queryParam with_deleted integer This param has no effect as api calls do not currently receive group permissions. + * @queryParam with_deleted boolean This param has no effect as api calls do not currently receive group permissions. No-example */ public function index() { diff --git a/app/Http/Controllers/ChangelogController.php b/app/Http/Controllers/ChangelogController.php index 983f96c218c..38e0897edf3 100644 --- a/app/Http/Controllers/ChangelogController.php +++ b/app/Http/Controllers/ChangelogController.php @@ -65,7 +65,7 @@ private static function changelogEntryMessageIncludes(?array $formats): array * @queryParam max_id integer Maximum build ID. No-example * @queryParam stream string Stream name to return builds from. No-example * @queryParam to string Maximum build version. No-example - * @queryParam message_formats[] string `html`, `markdown`. Default to both. + * @queryParam message_formats[] string `html`, `markdown`. Default to both. No-example * @response { * "streams": [ * { diff --git a/app/Http/Controllers/CommentsController.php b/app/Http/Controllers/CommentsController.php index ff70c363497..81414c13d63 100644 --- a/app/Http/Controllers/CommentsController.php +++ b/app/Http/Controllers/CommentsController.php @@ -181,10 +181,10 @@ public function show($id) * * Returns [CommentBundle](#commentbundle) * - * @queryParam comment.commentable_id integer required Resource ID the comment thread is attached to - * @queryParam comment.commentable_type string required Resource type the comment thread is attached to + * @queryParam comment.commentable_id integer required Resource ID the comment thread is attached to. Example: 1 + * @queryParam comment.commentable_type string required Resource type the comment thread is attached to. Example: beatmapset * @queryParam comment.message string required Text of the comment - * @queryParam comment.parent_id integer The id of the comment to reply to, null if not a reply + * @queryParam comment.parent_id integer The id of the comment to reply to, null if not a reply. No-example */ public function store() { From 7fe4e1ffae1d853dea45700a3001e3f2bd6cd81a Mon Sep 17 00:00:00 2001 From: bakaneko Date: Wed, 14 Aug 2024 19:24:56 +0900 Subject: [PATCH 14/25] use attribute for limit queryParam --- app/Docs/Attributes/Limit.php | 29 +++++++++++++++++++ app/Docs/Strategies/QueryParamLimit.php | 16 ++++++++++ .../BeatmapDiscussionPostsController.php | 4 ++- .../BeatmapDiscussionsController.php | 3 +- .../BeatmapsetDiscussionVotesController.php | 3 +- .../Chat/Channels/MessagesController.php | 3 +- app/Http/Controllers/CommentsController.php | 2 ++ .../Controllers/Forum/TopicsController.php | 2 ++ app/Http/Controllers/MatchesController.php | 5 ++-- .../Rooms/Playlist/ScoresController.php | 3 +- .../Multiplayer/RoomsController.php | 3 +- app/Http/Controllers/NewsController.php | 3 +- app/Http/Controllers/UsersController.php | 9 +++--- config/scribe.php | 4 +++ 14 files changed, 76 insertions(+), 13 deletions(-) create mode 100644 app/Docs/Attributes/Limit.php create mode 100644 app/Docs/Strategies/QueryParamLimit.php diff --git a/app/Docs/Attributes/Limit.php b/app/Docs/Attributes/Limit.php new file mode 100644 index 00000000000..102bec6df29 --- /dev/null +++ b/app/Docs/Attributes/Limit.php @@ -0,0 +1,29 @@ +. Licensed under the GNU Affero General Public License v3.0. +// See the LICENCE file in the repository root for full licence text. + +declare(strict_types=1); + +namespace App\Docs\Attributes; + +use Attribute; +use Knuckles\Scribe\Attributes\GenericParam; + +#[Attribute(Attribute::IS_REPEATABLE | Attribute::TARGET_FUNCTION | Attribute::TARGET_METHOD | Attribute::TARGET_CLASS)] +class Limit extends GenericParam +{ + public function __construct( + int $default = 20, // values are defaults on pagination() + int $minimum = 5, + int $maximum = 50, + string $description = 'Maximum number of results', + bool $required = false, + string|int $example = 'No-example', + ) { + $description .= " (Default: {$default}, Minimum: {$minimum}, Maximum: {$maximum})"; + + parent::__construct('limit', 'integer', $description, $required, $example); + } +} + diff --git a/app/Docs/Strategies/QueryParamLimit.php b/app/Docs/Strategies/QueryParamLimit.php new file mode 100644 index 00000000000..740224f77a6 --- /dev/null +++ b/app/Docs/Strategies/QueryParamLimit.php @@ -0,0 +1,16 @@ +. Licensed under the GNU Affero General Public License v3.0. +// See the LICENCE file in the repository root for full licence text. + +declare(strict_types=1); + +namespace App\Docs\Strategies; + +use App\Docs\Attributes\Limit; +use Knuckles\Scribe\Extracting\Strategies\GetParamsFromAttributeStrategy; + +class QueryParamLimit extends GetParamsFromAttributeStrategy +{ + protected static array $attributeNames = [Limit::class]; +} diff --git a/app/Http/Controllers/BeatmapDiscussionPostsController.php b/app/Http/Controllers/BeatmapDiscussionPostsController.php index 9fdbc7a6dbc..680673cd18e 100644 --- a/app/Http/Controllers/BeatmapDiscussionPostsController.php +++ b/app/Http/Controllers/BeatmapDiscussionPostsController.php @@ -5,6 +5,7 @@ namespace App\Http\Controllers; +use App\Docs\Attributes\Limit; use App\Exceptions\ModelNotSavedException; use App\Libraries\BeatmapsetDiscussion\Discussion; use App\Libraries\BeatmapsetDiscussion\Reply; @@ -15,6 +16,7 @@ use App\Models\Beatmapset; use App\Models\BeatmapsetWatch; use App\Models\User; +use Knuckles\Scribe\Attributes\QueryParam; /** * @group Beatmapset Discussions @@ -65,13 +67,13 @@ public function destroy($id) * * @usesCursor * @queryParam beatmapset_discussion_id integer `id` of the [BeatmapsetDiscussion](#beatmapsetdiscussion). - * @queryParam limit integer Maximum number of results. * @queryParam page integer Search result page. * @queryParam sort string `id_desc` for newest first; `id_asc` for oldest first. Defaults to `id_desc`. * @queryParam types string[] `first`, `reply`, `system` are the valid values. Defaults to `reply`. * @queryParam user integer The `id` of the [User](#user). * @queryParam with_deleted boolean This param has no effect as api calls do not currently receive group permissions. */ + #[Limit] public function index() { $bundle = new BeatmapsetDiscussionPostsBundle(request()->all()); diff --git a/app/Http/Controllers/BeatmapDiscussionsController.php b/app/Http/Controllers/BeatmapDiscussionsController.php index 750ebc4388d..fb73b14c789 100644 --- a/app/Http/Controllers/BeatmapDiscussionsController.php +++ b/app/Http/Controllers/BeatmapDiscussionsController.php @@ -5,6 +5,7 @@ namespace App\Http\Controllers; +use App\Docs\Attributes\Limit; use App\Exceptions\ModelNotSavedException; use App\Libraries\BeatmapsetDiscussion\Review; use App\Libraries\BeatmapsetDiscussionsBundle; @@ -93,7 +94,6 @@ public function destroy($id) * @queryParam beatmap_id integer `id` of the [Beatmap](#beatmap). * @queryParam beatmapset_id integer `id` of the [Beatmapset](#beatmapset). * @queryParam beatmapset_status string One of `all`, `ranked`, `qualified`, `disqualified`, `never_qualified`. Defaults to `all`. TODO: better descriptions. No-example - * @queryParam limit integer Maximum number of results. * @queryParam message_types string[] `suggestion`, `problem`, `mapper_note`, `praise`, `hype`, `review`. Blank defaults to all types. TODO: better descriptions. No-example * @queryParam only_unresolved boolean `true` to show only unresolved issues; `false`, otherwise. Defaults to `false`. * @queryParam page integer Search result page. @@ -101,6 +101,7 @@ public function destroy($id) * @queryParam user integer The `id` of the [User](#user). * @queryParam with_deleted boolean This param has no effect as api calls do not currently receive group permissions. No-example */ + #[Limit] public function index() { $bundle = new BeatmapsetDiscussionsBundle(request()->all()); diff --git a/app/Http/Controllers/BeatmapsetDiscussionVotesController.php b/app/Http/Controllers/BeatmapsetDiscussionVotesController.php index 7297230a905..2ad8c0fcf6d 100644 --- a/app/Http/Controllers/BeatmapsetDiscussionVotesController.php +++ b/app/Http/Controllers/BeatmapsetDiscussionVotesController.php @@ -5,6 +5,7 @@ namespace App\Http\Controllers; +use App\Docs\Attributes\Limit; use App\Libraries\BeatmapsetDiscussionVotesBundle; /** @@ -41,7 +42,6 @@ public function __construct() * * @usesCursor * @queryParam beatmapset_discussion_id integer `id` of the [BeatmapsetDiscussion](#beatmapsetdiscussion). - * @queryParam limit integer Maximum number of results. No-example * @queryParam page integer Search result page. No-example * @queryParam receiver integer The `id` of the [User](#user) receiving the votes. * @queryParam score integer `1` for up vote, `-1` for down vote. Example: 1 @@ -49,6 +49,7 @@ public function __construct() * @queryParam user integer The `id` of the [User](#user) giving the votes. * @queryParam with_deleted boolean This param has no effect as api calls do not currently receive group permissions. No-example */ + #[Limit] public function index() { $bundle = new BeatmapsetDiscussionVotesBundle(request()->all()); diff --git a/app/Http/Controllers/Chat/Channels/MessagesController.php b/app/Http/Controllers/Chat/Channels/MessagesController.php index 23af90f72fd..30e9e861e74 100644 --- a/app/Http/Controllers/Chat/Channels/MessagesController.php +++ b/app/Http/Controllers/Chat/Channels/MessagesController.php @@ -5,6 +5,7 @@ namespace App\Http\Controllers\Chat\Channels; +use App\Docs\Attributes\Limit; use App\Http\Controllers\Chat\Controller as BaseController; use App\Libraries\Chat; use App\Models\Chat\Channel; @@ -37,7 +38,6 @@ public function __construct() * Returns an array of [ChatMessage](#chatmessage) * * @urlParam channel integer required The ID of the channel to retrieve messages for - * @queryParam limit integer number of messages to return (max of 50) * @queryParam since integer messages after the specified message id will be returned * @queryParam until integer messages up to but not including the specified message id will be returned * @@ -82,6 +82,7 @@ public function __construct() * } * ] */ + #[Limit(50, 1, 50)] public function index($channelId) { [ diff --git a/app/Http/Controllers/CommentsController.php b/app/Http/Controllers/CommentsController.php index 81414c13d63..9485cc9f72c 100644 --- a/app/Http/Controllers/CommentsController.php +++ b/app/Http/Controllers/CommentsController.php @@ -15,6 +15,7 @@ use Carbon\Carbon; use Exception; use Illuminate\Pagination\LengthAwarePaginator; +use Knuckles\Scribe\Attributes\QueryParam; /** * @group Comments @@ -76,6 +77,7 @@ public function destroy($id) * @queryParam parent_id integer Limit to comments which are reply to the specified id. Specify 0 to get top level comments. Example: 1 * @queryParam sort string Sort option as defined in [CommentSort](#commentsort). Defaults to `new` for guests and user-specified default when authenticated. Example: new */ + #[QueryParam('derp', 'integer')] public function index() { $params = request()->all(); diff --git a/app/Http/Controllers/Forum/TopicsController.php b/app/Http/Controllers/Forum/TopicsController.php index a98bf428698..1506bfb112f 100644 --- a/app/Http/Controllers/Forum/TopicsController.php +++ b/app/Http/Controllers/Forum/TopicsController.php @@ -5,6 +5,7 @@ namespace App\Http\Controllers\Forum; +use App\Docs\Attributes\Limit; use App\Exceptions\ModelNotSavedException; use App\Jobs\Notifications\ForumTopicReply; use App\Libraries\NewForumTopic; @@ -313,6 +314,7 @@ public function reply($id) * "sort": "id_asc" * } */ + #[Limit(20, 1, 50, 'Maximum number of posts to be returned')] public function show($id) { $topic = Topic::with(['forum'])->withTrashed()->findOrFail($id); diff --git a/app/Http/Controllers/MatchesController.php b/app/Http/Controllers/MatchesController.php index f471caf0fa8..4ced4518e89 100644 --- a/app/Http/Controllers/MatchesController.php +++ b/app/Http/Controllers/MatchesController.php @@ -5,6 +5,7 @@ namespace App\Http\Controllers; +use App\Docs\Attributes\Limit; use App\Models\LegacyMatch\LegacyMatch; use App\Models\User; use App\Transformers\LegacyMatch\EventTransformer; @@ -38,7 +39,6 @@ public function __construct() * params.sort | string | | * * @usesCursor - * @queryParam limit integer Maximum number of matches (50 default, 1 minimum, 50 maximum). No-example * @queryParam sort string `id_desc` for newest first; `id_asc` for oldest first. Defaults to `id_desc`. No-example * @response { * "matches": [ @@ -60,6 +60,7 @@ public function __construct() * "cursor_string": "eyJtYXRjaF9pZCI6MTE0NDI4Njg1fQ" * } */ + #[Limit(50, 1, 50)] public function index() { $params = request()->all(); @@ -99,7 +100,6 @@ public function index() * @urlParam match integer required Match ID. No-example * @queryParam before integer Filter for match events before the specified [MatchEvent.id](#matchevent). No-example * @queryParam after integer Filter for match events after the specified [MatchEvent.id](#matchevent). No-example - * @queryParam limit integer Maximum number of match events (100 default, 1 minimum, 101 maximum). No-example * @response { * "match": { * "id": 16155689, @@ -124,6 +124,7 @@ public function index() * "current_game_id": null * } */ + #[Limit(100, 1, 101)] public function show($id) { $match = LegacyMatch::findOrFail($id); diff --git a/app/Http/Controllers/Multiplayer/Rooms/Playlist/ScoresController.php b/app/Http/Controllers/Multiplayer/Rooms/Playlist/ScoresController.php index ea1f7321d1f..54a50a184f9 100644 --- a/app/Http/Controllers/Multiplayer/Rooms/Playlist/ScoresController.php +++ b/app/Http/Controllers/Multiplayer/Rooms/Playlist/ScoresController.php @@ -5,6 +5,7 @@ namespace App\Http\Controllers\Multiplayer\Rooms\Playlist; +use App\Docs\Attributes\Limit; use App\Exceptions\InvariantException; use App\Http\Controllers\Controller as BaseController; use App\Libraries\ClientCheck; @@ -43,9 +44,9 @@ public function __construct() * @urlParam playlist integer required Id of the playlist item. * * @usesCursor - * @queryParam limit Number of scores to be returned. * @queryParam sort [MultiplayerScoresSort](#multiplayerscoressort) parameter. */ + #[Limit(50, 1, 50)] public function index($roomId, $playlistId) { $playlist = PlaylistItem::where('room_id', $roomId)->findOrFail($playlistId); diff --git a/app/Http/Controllers/Multiplayer/RoomsController.php b/app/Http/Controllers/Multiplayer/RoomsController.php index 33e7e7c13c4..62454726e6b 100644 --- a/app/Http/Controllers/Multiplayer/RoomsController.php +++ b/app/Http/Controllers/Multiplayer/RoomsController.php @@ -5,6 +5,7 @@ namespace App\Http\Controllers\Multiplayer; +use App\Docs\Attributes\Limit; use App\Exceptions\InvariantException; use App\Http\Controllers\Controller; use App\Http\Controllers\Ranking\DailyChallengeController; @@ -34,12 +35,12 @@ public function destroy($id) * * @group Multiplayer * - * @queryParam limit Maximum number of results. No-example * @queryParam mode Filter mode; `active` (default), `all`, `ended`, `participated`, `owned`. No-example * @queryParam season_id Season ID to return Rooms from. No-example * @queryParam sort Sort order; `ended`, `created`. No-example * @queryParam type_group `playlists` (default) or `realtime`. No-example */ + #[Limit(250, 1, 250)] public function index() { $apiVersion = api_version(); diff --git a/app/Http/Controllers/NewsController.php b/app/Http/Controllers/NewsController.php index 8fa04aeb12a..f77fa4945a9 100644 --- a/app/Http/Controllers/NewsController.php +++ b/app/Http/Controllers/NewsController.php @@ -5,6 +5,7 @@ namespace App\Http\Controllers; +use App\Docs\Attributes\Limit; use App\Libraries\CommentBundle; use App\Models\NewsPost; @@ -37,7 +38,6 @@ class NewsController extends Controller * * * @usesCursor - * @queryParam limit integer Maximum number of posts (12 default, 1 minimum, 21 maximum). No-example * @queryParam year integer Year to return posts from. No-example * @response { * "news_posts": [ @@ -78,6 +78,7 @@ class NewsController extends Controller * "cursor_string": "WyJodHRwczpcL1wvd3d3LnlvdXR1YmUuY29tXC93YXRjaD92PWRRdzR3OVdnWGNRIl0" * } */ + #[Limit(12, 1, 21)] public function index() { $params = request()->all(); diff --git a/app/Http/Controllers/UsersController.php b/app/Http/Controllers/UsersController.php index 3c5512c29ae..9f34c3a598e 100644 --- a/app/Http/Controllers/UsersController.php +++ b/app/Http/Controllers/UsersController.php @@ -5,6 +5,7 @@ namespace App\Http\Controllers; +use App\Docs\Attributes\Limit; use App\Exceptions\ModelNotSavedException; use App\Exceptions\ValidationException; use App\Http\Middleware\RequestCost; @@ -280,7 +281,6 @@ public function storeWeb() * @urlParam user integer required Id of the user. Example: 1 * @urlParam type string required Beatmap type. Example: favourite * - * @queryParam limit Maximum number of results. * @queryParam offset Result offset for pagination. Example: 1 * * @response [ @@ -294,6 +294,7 @@ public function storeWeb() * } * ] */ + #[Limit(5, 1, 100)] public function beatmapsets($_userId, $type) { static $mapping = [ @@ -430,7 +431,6 @@ public function posts($id) * * @urlParam user integer required Id of the user. Example: 1 * - * @queryParam limit Maximum number of results. * @queryParam offset Result offset for pagination. Example: 1 * * @response [ @@ -444,6 +444,7 @@ public function posts($id) * } * ] */ + #[Limit(5, 1, 100)] public function kudosu($_userId) { return $this->getExtra('recentlyReceivedKudosu', [], $this->perPage, $this->offset); @@ -462,7 +463,6 @@ public function kudosu($_userId) * * @urlParam user integer required Id of the user. Example: 1 * - * @queryParam limit Maximum number of results. * @queryParam offset Result offset for pagination. Example: 1 * * @response [ @@ -476,6 +476,7 @@ public function kudosu($_userId) * } * ] */ + #[Limit(5, 1, 100)] public function recentActivity($_userId) { return $this->getExtra('recentActivity', [], $this->perPage, $this->offset); @@ -505,7 +506,6 @@ public function recentActivity($_userId) * @queryParam legacy_only integer Whether or not to exclude lazer scores. Defaults to 0. Example: 0 * @queryParam include_fails integer Only for recent scores, include scores of failed plays. Set to 1 to include them. Defaults to 0. Example: 0 * @queryParam mode string [Ruleset](#ruleset) of the scores to be returned. Defaults to the specified `user`'s mode. Example: osu - * @queryParam limit integer Maximum number of results. * @queryParam offset integer Result offset for pagination. Example: 1 * * @response [ @@ -519,6 +519,7 @@ public function recentActivity($_userId) * } * ] */ + #[Limit(5, 1, 100)] public function scores($_userId, $type) { static $mapping = [ diff --git a/config/scribe.php b/config/scribe.php index 38ea83d10ad..2b910066559 100644 --- a/config/scribe.php +++ b/config/scribe.php @@ -300,16 +300,20 @@ 'strategies' => [ 'metadata' => [ Strategies\Metadata\GetFromDocBlocks::class, + Strategies\Metadata\GetFromMetadataAttributes::class, ], 'urlParameters' => [ Strategies\UrlParameters\GetFromLaravelAPI::class, Strategies\UrlParameters\GetFromLumenAPI::class, + Strategies\UrlParameters\GetFromUrlParamAttribute::class, Strategies\UrlParameters\GetFromUrlParamTag::class, ], 'queryParameters' => [ + Strategies\QueryParameters\GetFromQueryParamAttribute::class, Strategies\QueryParameters\GetFromQueryParamTag::class, Strategies\QueryParameters\GetFromFormRequest::class, Strategies\QueryParameters\GetFromInlineValidator::class, + App\Docs\Strategies\QueryParamLimit::class, App\Docs\Strategies\UsesCursor::class, ], 'headers' => [ From 45b854e1509e0979aa54bf56cebaec0e0aa9ca0b Mon Sep 17 00:00:00 2001 From: bakaneko Date: Wed, 14 Aug 2024 19:33:08 +0900 Subject: [PATCH 15/25] use attribute for page param --- app/Docs/Attributes/Page.php | 24 +++++++++++++++++++ app/Docs/Strategies/QueryParamLimit.php | 3 ++- .../BeatmapDiscussionPostsController.php | 4 ++-- .../BeatmapDiscussionsController.php | 4 ++-- .../BeatmapsetDiscussionVotesController.php | 4 ++-- app/Http/Controllers/HomeController.php | 3 ++- app/Http/Controllers/RankingController.php | 4 ++-- 7 files changed, 36 insertions(+), 10 deletions(-) create mode 100644 app/Docs/Attributes/Page.php diff --git a/app/Docs/Attributes/Page.php b/app/Docs/Attributes/Page.php new file mode 100644 index 00000000000..99c7b3c65c4 --- /dev/null +++ b/app/Docs/Attributes/Page.php @@ -0,0 +1,24 @@ +. Licensed under the GNU Affero General Public License v3.0. +// See the LICENCE file in the repository root for full licence text. + +declare(strict_types=1); + +namespace App\Docs\Attributes; + +use Attribute; +use Knuckles\Scribe\Attributes\GenericParam; + +#[Attribute(Attribute::IS_REPEATABLE | Attribute::TARGET_FUNCTION | Attribute::TARGET_METHOD | Attribute::TARGET_CLASS)] +class Page extends GenericParam +{ + public function __construct( + string $description = 'Search result page', + bool $required = false, + ?int $example = 1, + ) { + parent::__construct('page', 'integer', $description, $required, $example ?? 'No-example'); + } +} + diff --git a/app/Docs/Strategies/QueryParamLimit.php b/app/Docs/Strategies/QueryParamLimit.php index 740224f77a6..52bfa912259 100644 --- a/app/Docs/Strategies/QueryParamLimit.php +++ b/app/Docs/Strategies/QueryParamLimit.php @@ -8,9 +8,10 @@ namespace App\Docs\Strategies; use App\Docs\Attributes\Limit; +use App\Docs\Attributes\Page; use Knuckles\Scribe\Extracting\Strategies\GetParamsFromAttributeStrategy; class QueryParamLimit extends GetParamsFromAttributeStrategy { - protected static array $attributeNames = [Limit::class]; + protected static array $attributeNames = [Limit::class, Page::class]; } diff --git a/app/Http/Controllers/BeatmapDiscussionPostsController.php b/app/Http/Controllers/BeatmapDiscussionPostsController.php index 680673cd18e..3b6d0940042 100644 --- a/app/Http/Controllers/BeatmapDiscussionPostsController.php +++ b/app/Http/Controllers/BeatmapDiscussionPostsController.php @@ -6,6 +6,7 @@ namespace App\Http\Controllers; use App\Docs\Attributes\Limit; +use App\Docs\Attributes\Page; use App\Exceptions\ModelNotSavedException; use App\Libraries\BeatmapsetDiscussion\Discussion; use App\Libraries\BeatmapsetDiscussion\Reply; @@ -67,13 +68,12 @@ public function destroy($id) * * @usesCursor * @queryParam beatmapset_discussion_id integer `id` of the [BeatmapsetDiscussion](#beatmapsetdiscussion). - * @queryParam page integer Search result page. * @queryParam sort string `id_desc` for newest first; `id_asc` for oldest first. Defaults to `id_desc`. * @queryParam types string[] `first`, `reply`, `system` are the valid values. Defaults to `reply`. * @queryParam user integer The `id` of the [User](#user). * @queryParam with_deleted boolean This param has no effect as api calls do not currently receive group permissions. */ - #[Limit] + #[Limit, Page] public function index() { $bundle = new BeatmapsetDiscussionPostsBundle(request()->all()); diff --git a/app/Http/Controllers/BeatmapDiscussionsController.php b/app/Http/Controllers/BeatmapDiscussionsController.php index fb73b14c789..570b7d5d364 100644 --- a/app/Http/Controllers/BeatmapDiscussionsController.php +++ b/app/Http/Controllers/BeatmapDiscussionsController.php @@ -6,6 +6,7 @@ namespace App\Http\Controllers; use App\Docs\Attributes\Limit; +use App\Docs\Attributes\Page; use App\Exceptions\ModelNotSavedException; use App\Libraries\BeatmapsetDiscussion\Review; use App\Libraries\BeatmapsetDiscussionsBundle; @@ -96,12 +97,11 @@ public function destroy($id) * @queryParam beatmapset_status string One of `all`, `ranked`, `qualified`, `disqualified`, `never_qualified`. Defaults to `all`. TODO: better descriptions. No-example * @queryParam message_types string[] `suggestion`, `problem`, `mapper_note`, `praise`, `hype`, `review`. Blank defaults to all types. TODO: better descriptions. No-example * @queryParam only_unresolved boolean `true` to show only unresolved issues; `false`, otherwise. Defaults to `false`. - * @queryParam page integer Search result page. * @queryParam sort string `id_desc` for newest first; `id_asc` for oldest first. Defaults to `id_desc`. No-example * @queryParam user integer The `id` of the [User](#user). * @queryParam with_deleted boolean This param has no effect as api calls do not currently receive group permissions. No-example */ - #[Limit] + #[Limit, Page] public function index() { $bundle = new BeatmapsetDiscussionsBundle(request()->all()); diff --git a/app/Http/Controllers/BeatmapsetDiscussionVotesController.php b/app/Http/Controllers/BeatmapsetDiscussionVotesController.php index 2ad8c0fcf6d..15ce797e220 100644 --- a/app/Http/Controllers/BeatmapsetDiscussionVotesController.php +++ b/app/Http/Controllers/BeatmapsetDiscussionVotesController.php @@ -6,6 +6,7 @@ namespace App\Http\Controllers; use App\Docs\Attributes\Limit; +use App\Docs\Attributes\Page; use App\Libraries\BeatmapsetDiscussionVotesBundle; /** @@ -42,14 +43,13 @@ public function __construct() * * @usesCursor * @queryParam beatmapset_discussion_id integer `id` of the [BeatmapsetDiscussion](#beatmapsetdiscussion). - * @queryParam page integer Search result page. No-example * @queryParam receiver integer The `id` of the [User](#user) receiving the votes. * @queryParam score integer `1` for up vote, `-1` for down vote. Example: 1 * @queryParam sort string `id_desc` for newest first; `id_asc` for oldest first. Defaults to `id_desc`. No-example * @queryParam user integer The `id` of the [User](#user) giving the votes. * @queryParam with_deleted boolean This param has no effect as api calls do not currently receive group permissions. No-example */ - #[Limit] + #[Limit, Page] public function index() { $bundle = new BeatmapsetDiscussionVotesBundle(request()->all()); diff --git a/app/Http/Controllers/HomeController.php b/app/Http/Controllers/HomeController.php index 0cd6ff043d9..66fb11aab1d 100644 --- a/app/Http/Controllers/HomeController.php +++ b/app/Http/Controllers/HomeController.php @@ -6,6 +6,7 @@ namespace App\Http\Controllers; use App; +use App\Docs\Attributes\Page; use App\Libraries\CurrentStats; use App\Libraries\MenuContent; use App\Libraries\Search\AllSearch; @@ -177,8 +178,8 @@ public function quickSearch() * * @queryParam mode string Either `all`, `user`, or `wiki_page`. Default is `all`. Example: all * @queryParam query Search keyword. Example: hello - * @queryParam page Search result page. Ignored for mode `all`. Example: 1 */ + #[Page('Search result page. Ignored for mode `all`')] public function search() { $currentUser = Auth::user(); diff --git a/app/Http/Controllers/RankingController.php b/app/Http/Controllers/RankingController.php index 8adfcb5ab69..da357464c8d 100644 --- a/app/Http/Controllers/RankingController.php +++ b/app/Http/Controllers/RankingController.php @@ -5,6 +5,7 @@ namespace App\Http\Controllers; +use App\Docs\Attributes\Page; use App\Models\Beatmap; use App\Models\Country; use App\Models\CountryStatistics; @@ -296,9 +297,8 @@ public function index($mode, $type) * Field | Type | Description * ------- | --------------- | ----------- * ranking | [User](#user)[] | Includes `kudosu`. - * - * @queryParam page Ranking page. Example: 1 */ + #[Page('Ranking page')] public function kudosu() { static $maxResults = 1000; From 2e3eadd256cb6d64d5d1c8059d34b0cab2f48423 Mon Sep 17 00:00:00 2001 From: bakaneko Date: Wed, 14 Aug 2024 19:35:33 +0900 Subject: [PATCH 16/25] combine strategy --- .../{QueryParamLimit.php => GetFromQueryParamAttribute.php} | 5 +++-- config/scribe.php | 5 ++--- 2 files changed, 5 insertions(+), 5 deletions(-) rename app/Docs/Strategies/{QueryParamLimit.php => GetFromQueryParamAttribute.php} (64%) diff --git a/app/Docs/Strategies/QueryParamLimit.php b/app/Docs/Strategies/GetFromQueryParamAttribute.php similarity index 64% rename from app/Docs/Strategies/QueryParamLimit.php rename to app/Docs/Strategies/GetFromQueryParamAttribute.php index 52bfa912259..0e4315737bf 100644 --- a/app/Docs/Strategies/QueryParamLimit.php +++ b/app/Docs/Strategies/GetFromQueryParamAttribute.php @@ -9,9 +9,10 @@ use App\Docs\Attributes\Limit; use App\Docs\Attributes\Page; +use Http\Message\Authentication\QueryParam; use Knuckles\Scribe\Extracting\Strategies\GetParamsFromAttributeStrategy; -class QueryParamLimit extends GetParamsFromAttributeStrategy +class GetFromQueryParamAttribute extends GetParamsFromAttributeStrategy { - protected static array $attributeNames = [Limit::class, Page::class]; + protected static array $attributeNames = [QueryParam::class, Limit::class, Page::class]; } diff --git a/config/scribe.php b/config/scribe.php index 2b910066559..815758cf403 100644 --- a/config/scribe.php +++ b/config/scribe.php @@ -309,12 +309,11 @@ Strategies\UrlParameters\GetFromUrlParamTag::class, ], 'queryParameters' => [ - Strategies\QueryParameters\GetFromQueryParamAttribute::class, + App\Docs\Strategies\GetFromQueryParamAttribute::class, + App\Docs\Strategies\UsesCursor::class, Strategies\QueryParameters\GetFromQueryParamTag::class, Strategies\QueryParameters\GetFromFormRequest::class, Strategies\QueryParameters\GetFromInlineValidator::class, - App\Docs\Strategies\QueryParamLimit::class, - App\Docs\Strategies\UsesCursor::class, ], 'headers' => [ Strategies\Headers\GetFromRouteRules::class, From bdf481b7152710fb6dac3ce64f1c5a907f53a001 Mon Sep 17 00:00:00 2001 From: bakaneko Date: Wed, 14 Aug 2024 19:42:31 +0900 Subject: [PATCH 17/25] offset attribute for query param doc --- app/Docs/Attributes/Offset.php | 24 +++++++++++++++++++ .../Strategies/GetFromQueryParamAttribute.php | 3 ++- app/Http/Controllers/UsersController.php | 18 +++++--------- 3 files changed, 32 insertions(+), 13 deletions(-) create mode 100644 app/Docs/Attributes/Offset.php diff --git a/app/Docs/Attributes/Offset.php b/app/Docs/Attributes/Offset.php new file mode 100644 index 00000000000..f8b98707b55 --- /dev/null +++ b/app/Docs/Attributes/Offset.php @@ -0,0 +1,24 @@ +. Licensed under the GNU Affero General Public License v3.0. +// See the LICENCE file in the repository root for full licence text. + +declare(strict_types=1); + +namespace App\Docs\Attributes; + +use Attribute; +use Knuckles\Scribe\Attributes\GenericParam; + +#[Attribute(Attribute::IS_REPEATABLE | Attribute::TARGET_FUNCTION | Attribute::TARGET_METHOD | Attribute::TARGET_CLASS)] +class Offset extends GenericParam +{ + public function __construct( + string $description = 'Result offset for pagination.', + bool $required = false, + ?int $example = 1, + ) { + parent::__construct('offset', 'integer', $description, $required, $example ?? 'No-example'); + } +} + diff --git a/app/Docs/Strategies/GetFromQueryParamAttribute.php b/app/Docs/Strategies/GetFromQueryParamAttribute.php index 0e4315737bf..123fec684a5 100644 --- a/app/Docs/Strategies/GetFromQueryParamAttribute.php +++ b/app/Docs/Strategies/GetFromQueryParamAttribute.php @@ -8,11 +8,12 @@ namespace App\Docs\Strategies; use App\Docs\Attributes\Limit; +use App\Docs\Attributes\Offset; use App\Docs\Attributes\Page; use Http\Message\Authentication\QueryParam; use Knuckles\Scribe\Extracting\Strategies\GetParamsFromAttributeStrategy; class GetFromQueryParamAttribute extends GetParamsFromAttributeStrategy { - protected static array $attributeNames = [QueryParam::class, Limit::class, Page::class]; + protected static array $attributeNames = [QueryParam::class, Limit::class, Offset::class, Page::class]; } diff --git a/app/Http/Controllers/UsersController.php b/app/Http/Controllers/UsersController.php index 9f34c3a598e..73ea2a0abfc 100644 --- a/app/Http/Controllers/UsersController.php +++ b/app/Http/Controllers/UsersController.php @@ -6,6 +6,7 @@ namespace App\Http\Controllers; use App\Docs\Attributes\Limit; +use App\Docs\Attributes\Offset; use App\Exceptions\ModelNotSavedException; use App\Exceptions\ValidationException; use App\Http\Middleware\RequestCost; @@ -281,8 +282,6 @@ public function storeWeb() * @urlParam user integer required Id of the user. Example: 1 * @urlParam type string required Beatmap type. Example: favourite * - * @queryParam offset Result offset for pagination. Example: 1 - * * @response [ * { * "id": 1, @@ -294,7 +293,7 @@ public function storeWeb() * } * ] */ - #[Limit(5, 1, 100)] + #[Limit(5, 1, 100), Offset] public function beatmapsets($_userId, $type) { static $mapping = [ @@ -431,8 +430,6 @@ public function posts($id) * * @urlParam user integer required Id of the user. Example: 1 * - * @queryParam offset Result offset for pagination. Example: 1 - * * @response [ * { * "id": 1, @@ -444,7 +441,7 @@ public function posts($id) * } * ] */ - #[Limit(5, 1, 100)] + #[Limit(5, 1, 100), Offset] public function kudosu($_userId) { return $this->getExtra('recentlyReceivedKudosu', [], $this->perPage, $this->offset); @@ -462,9 +459,7 @@ public function kudosu($_userId) * Array of [Event](#event). * * @urlParam user integer required Id of the user. Example: 1 - * - * @queryParam offset Result offset for pagination. Example: 1 - * + * * * @response [ * { * "id": 1, @@ -476,7 +471,7 @@ public function kudosu($_userId) * } * ] */ - #[Limit(5, 1, 100)] + #[Limit(5, 1, 100), Offset] public function recentActivity($_userId) { return $this->getExtra('recentActivity', [], $this->perPage, $this->offset); @@ -506,7 +501,6 @@ public function recentActivity($_userId) * @queryParam legacy_only integer Whether or not to exclude lazer scores. Defaults to 0. Example: 0 * @queryParam include_fails integer Only for recent scores, include scores of failed plays. Set to 1 to include them. Defaults to 0. Example: 0 * @queryParam mode string [Ruleset](#ruleset) of the scores to be returned. Defaults to the specified `user`'s mode. Example: osu - * @queryParam offset integer Result offset for pagination. Example: 1 * * @response [ * { @@ -519,7 +513,7 @@ public function recentActivity($_userId) * } * ] */ - #[Limit(5, 1, 100)] + #[Limit(5, 1, 100), Offset] public function scores($_userId, $type) { static $mapping = [ From 85aa097c102590ac74792c12d92a0d509c962f17 Mon Sep 17 00:00:00 2001 From: bakaneko Date: Wed, 14 Aug 2024 20:20:13 +0900 Subject: [PATCH 18/25] attributes for sort query params in api doc --- app/Docs/Attributes/SortCustom.php | 35 +++++++++++++++++++ app/Docs/Attributes/SortId.php | 24 +++++++++++++ .../Strategies/GetFromQueryParamAttribute.php | 11 +++++- .../BeatmapDiscussionPostsController.php | 4 +-- .../BeatmapDiscussionsController.php | 4 +-- .../BeatmapsetDiscussionVotesController.php | 4 +-- app/Http/Controllers/CommentsController.php | 4 +-- app/Http/Controllers/EventsController.php | 3 +- .../Controllers/Forum/TopicsController.php | 4 +-- app/Http/Controllers/MatchesController.php | 4 +-- .../Rooms/Playlist/ScoresController.php | 3 +- .../Multiplayer/RoomsController.php | 4 +-- 12 files changed, 87 insertions(+), 17 deletions(-) create mode 100644 app/Docs/Attributes/SortCustom.php create mode 100644 app/Docs/Attributes/SortId.php diff --git a/app/Docs/Attributes/SortCustom.php b/app/Docs/Attributes/SortCustom.php new file mode 100644 index 00000000000..ba645cb93f6 --- /dev/null +++ b/app/Docs/Attributes/SortCustom.php @@ -0,0 +1,35 @@ +. Licensed under the GNU Affero General Public License v3.0. +// See the LICENCE file in the repository root for full licence text. + +declare(strict_types=1); + +namespace App\Docs\Attributes; + +use Attribute; +use Knuckles\Scribe\Attributes\GenericParam; + +#[Attribute(Attribute::IS_REPEATABLE | Attribute::TARGET_FUNCTION | Attribute::TARGET_METHOD | Attribute::TARGET_CLASS)] +class SortCustom extends GenericParam +{ + public function __construct( + array|string $sorts, + ?string $defaultText = null, + ?string $example = null, + ) { + if (is_string($sorts)) { + $hash = mb_strtolower($sorts); + $description = "Sort option as defined in [{$sorts}](#{$hash})."; + } else { + $description = 'Sort order; '.implode(', ', array_map(fn ($sort) => "`{$sort}`", $sorts)); + } + + if ($defaultText !== null) { + $description .= " {$defaultText}"; + } + + parent::__construct('sort', 'string', $description, false, $example ?? 'No-example'); + } +} + diff --git a/app/Docs/Attributes/SortId.php b/app/Docs/Attributes/SortId.php new file mode 100644 index 00000000000..bf615aeb192 --- /dev/null +++ b/app/Docs/Attributes/SortId.php @@ -0,0 +1,24 @@ +. Licensed under the GNU Affero General Public License v3.0. +// See the LICENCE file in the repository root for full licence text. + +declare(strict_types=1); + +namespace App\Docs\Attributes; + +use Attribute; +use Knuckles\Scribe\Attributes\GenericParam; + +#[Attribute(Attribute::IS_REPEATABLE | Attribute::TARGET_FUNCTION | Attribute::TARGET_METHOD | Attribute::TARGET_CLASS)] +class SortId extends GenericParam +{ + public function __construct( + string $description = '`id_desc` for newest first; `id_asc` for oldest first. Defaults to `id_desc`.', + bool $required = false, + ?string $example = null, + ) { + parent::__construct('sort', 'string', $description, $required, $example ?? 'No-example'); + } +} + diff --git a/app/Docs/Strategies/GetFromQueryParamAttribute.php b/app/Docs/Strategies/GetFromQueryParamAttribute.php index 123fec684a5..8669f2f9f8a 100644 --- a/app/Docs/Strategies/GetFromQueryParamAttribute.php +++ b/app/Docs/Strategies/GetFromQueryParamAttribute.php @@ -10,10 +10,19 @@ use App\Docs\Attributes\Limit; use App\Docs\Attributes\Offset; use App\Docs\Attributes\Page; +use App\Docs\Attributes\SortCustom; +use App\Docs\Attributes\SortId; use Http\Message\Authentication\QueryParam; use Knuckles\Scribe\Extracting\Strategies\GetParamsFromAttributeStrategy; class GetFromQueryParamAttribute extends GetParamsFromAttributeStrategy { - protected static array $attributeNames = [QueryParam::class, Limit::class, Offset::class, Page::class]; + protected static array $attributeNames = [ + Limit::class, + Offset::class, + Page::class, + QueryParam::class, + SortCustom::class, + SortId::class, + ]; } diff --git a/app/Http/Controllers/BeatmapDiscussionPostsController.php b/app/Http/Controllers/BeatmapDiscussionPostsController.php index 3b6d0940042..0c3abd81990 100644 --- a/app/Http/Controllers/BeatmapDiscussionPostsController.php +++ b/app/Http/Controllers/BeatmapDiscussionPostsController.php @@ -7,6 +7,7 @@ use App\Docs\Attributes\Limit; use App\Docs\Attributes\Page; +use App\Docs\Attributes\SortId; use App\Exceptions\ModelNotSavedException; use App\Libraries\BeatmapsetDiscussion\Discussion; use App\Libraries\BeatmapsetDiscussion\Reply; @@ -68,12 +69,11 @@ public function destroy($id) * * @usesCursor * @queryParam beatmapset_discussion_id integer `id` of the [BeatmapsetDiscussion](#beatmapsetdiscussion). - * @queryParam sort string `id_desc` for newest first; `id_asc` for oldest first. Defaults to `id_desc`. * @queryParam types string[] `first`, `reply`, `system` are the valid values. Defaults to `reply`. * @queryParam user integer The `id` of the [User](#user). * @queryParam with_deleted boolean This param has no effect as api calls do not currently receive group permissions. */ - #[Limit, Page] + #[Limit, Page, SortId] public function index() { $bundle = new BeatmapsetDiscussionPostsBundle(request()->all()); diff --git a/app/Http/Controllers/BeatmapDiscussionsController.php b/app/Http/Controllers/BeatmapDiscussionsController.php index 570b7d5d364..c7c57033482 100644 --- a/app/Http/Controllers/BeatmapDiscussionsController.php +++ b/app/Http/Controllers/BeatmapDiscussionsController.php @@ -7,6 +7,7 @@ use App\Docs\Attributes\Limit; use App\Docs\Attributes\Page; +use App\Docs\Attributes\SortId; use App\Exceptions\ModelNotSavedException; use App\Libraries\BeatmapsetDiscussion\Review; use App\Libraries\BeatmapsetDiscussionsBundle; @@ -97,11 +98,10 @@ public function destroy($id) * @queryParam beatmapset_status string One of `all`, `ranked`, `qualified`, `disqualified`, `never_qualified`. Defaults to `all`. TODO: better descriptions. No-example * @queryParam message_types string[] `suggestion`, `problem`, `mapper_note`, `praise`, `hype`, `review`. Blank defaults to all types. TODO: better descriptions. No-example * @queryParam only_unresolved boolean `true` to show only unresolved issues; `false`, otherwise. Defaults to `false`. - * @queryParam sort string `id_desc` for newest first; `id_asc` for oldest first. Defaults to `id_desc`. No-example * @queryParam user integer The `id` of the [User](#user). * @queryParam with_deleted boolean This param has no effect as api calls do not currently receive group permissions. No-example */ - #[Limit, Page] + #[Limit, Page, SortId] public function index() { $bundle = new BeatmapsetDiscussionsBundle(request()->all()); diff --git a/app/Http/Controllers/BeatmapsetDiscussionVotesController.php b/app/Http/Controllers/BeatmapsetDiscussionVotesController.php index 15ce797e220..cd8cbc03454 100644 --- a/app/Http/Controllers/BeatmapsetDiscussionVotesController.php +++ b/app/Http/Controllers/BeatmapsetDiscussionVotesController.php @@ -7,6 +7,7 @@ use App\Docs\Attributes\Limit; use App\Docs\Attributes\Page; +use App\Docs\Attributes\SortId; use App\Libraries\BeatmapsetDiscussionVotesBundle; /** @@ -45,11 +46,10 @@ public function __construct() * @queryParam beatmapset_discussion_id integer `id` of the [BeatmapsetDiscussion](#beatmapsetdiscussion). * @queryParam receiver integer The `id` of the [User](#user) receiving the votes. * @queryParam score integer `1` for up vote, `-1` for down vote. Example: 1 - * @queryParam sort string `id_desc` for newest first; `id_asc` for oldest first. Defaults to `id_desc`. No-example * @queryParam user integer The `id` of the [User](#user) giving the votes. * @queryParam with_deleted boolean This param has no effect as api calls do not currently receive group permissions. No-example */ - #[Limit, Page] + #[Limit, Page, SortId] public function index() { $bundle = new BeatmapsetDiscussionVotesBundle(request()->all()); diff --git a/app/Http/Controllers/CommentsController.php b/app/Http/Controllers/CommentsController.php index 9485cc9f72c..9cb3befc969 100644 --- a/app/Http/Controllers/CommentsController.php +++ b/app/Http/Controllers/CommentsController.php @@ -5,6 +5,7 @@ namespace App\Http\Controllers; +use App\Docs\Attributes\SortCustom; use App\Exceptions\ModelNotSavedException; use App\Jobs\Notifications\CommentNew; use App\Libraries\CommentBundle; @@ -75,9 +76,8 @@ public function destroy($id) * @queryParam commentable_id integer The id of the resource to get comments for. Example: 1 * @queryParam cursor Pagination option. See [CommentSort](#commentsort) for detail. The format follows [Cursor](#cursor) except it's not currently included in the response. No-example * @queryParam parent_id integer Limit to comments which are reply to the specified id. Specify 0 to get top level comments. Example: 1 - * @queryParam sort string Sort option as defined in [CommentSort](#commentsort). Defaults to `new` for guests and user-specified default when authenticated. Example: new */ - #[QueryParam('derp', 'integer')] + #[SortCustom('CommentSort', 'Defaults to `new` for guests and user-specified default when authenticated.', 'new')] public function index() { $params = request()->all(); diff --git a/app/Http/Controllers/EventsController.php b/app/Http/Controllers/EventsController.php index 14a1a5d4ebf..3573e166528 100644 --- a/app/Http/Controllers/EventsController.php +++ b/app/Http/Controllers/EventsController.php @@ -7,6 +7,7 @@ namespace App\Http\Controllers; +use App\Docs\Attributes\SortId; use App\Models\Event; /** @@ -36,7 +37,6 @@ public function __construct() * events | [Event](#event)[] * * @usesCursor - * @queryParam sort Sorting option. Valid values are `id_desc` (default) and `id_asc`. No-example * * @response { * events: [ @@ -52,6 +52,7 @@ public function __construct() * cursor_string: "eyJldmVudF9pZCI6OH0" * } */ + #[SortId] public function index() { $params = request()->all(); diff --git a/app/Http/Controllers/Forum/TopicsController.php b/app/Http/Controllers/Forum/TopicsController.php index 1506bfb112f..6647045de02 100644 --- a/app/Http/Controllers/Forum/TopicsController.php +++ b/app/Http/Controllers/Forum/TopicsController.php @@ -6,6 +6,7 @@ namespace App\Http\Controllers\Forum; use App\Docs\Attributes\Limit; +use App\Docs\Attributes\SortId; use App\Exceptions\ModelNotSavedException; use App\Jobs\Notifications\ForumTopicReply; use App\Libraries\NewForumTopic; @@ -299,7 +300,6 @@ public function reply($id) * @urlParam topic integer required Id of the topic. Example: 1 * * @usesCursor - * @queryParam sort Post sorting option. Valid values are `id_asc` (default) and `id_desc`. No-example * @queryParam limit Maximum number of posts to be returned (20 default, 50 at most). No-example * @queryParam start First post id to be returned with `sort` set to `id_asc`. This parameter is ignored if `cursor_string` is specified. No-example * @queryParam end First post id to be returned with `sort` set to `id_desc`. This parameter is ignored if `cursor_string` is specified. No-example @@ -314,7 +314,7 @@ public function reply($id) * "sort": "id_asc" * } */ - #[Limit(20, 1, 50, 'Maximum number of posts to be returned')] + #[Limit(20, 1, 50, 'Maximum number of posts to be returned'), SortId] public function show($id) { $topic = Topic::with(['forum'])->withTrashed()->findOrFail($id); diff --git a/app/Http/Controllers/MatchesController.php b/app/Http/Controllers/MatchesController.php index 4ced4518e89..7dfec57b866 100644 --- a/app/Http/Controllers/MatchesController.php +++ b/app/Http/Controllers/MatchesController.php @@ -6,6 +6,7 @@ namespace App\Http\Controllers; use App\Docs\Attributes\Limit; +use App\Docs\Attributes\SortId; use App\Models\LegacyMatch\LegacyMatch; use App\Models\User; use App\Transformers\LegacyMatch\EventTransformer; @@ -39,7 +40,6 @@ public function __construct() * params.sort | string | | * * @usesCursor - * @queryParam sort string `id_desc` for newest first; `id_asc` for oldest first. Defaults to `id_desc`. No-example * @response { * "matches": [ * { @@ -60,7 +60,7 @@ public function __construct() * "cursor_string": "eyJtYXRjaF9pZCI6MTE0NDI4Njg1fQ" * } */ - #[Limit(50, 1, 50)] + #[Limit(50, 1, 50), SortId] public function index() { $params = request()->all(); diff --git a/app/Http/Controllers/Multiplayer/Rooms/Playlist/ScoresController.php b/app/Http/Controllers/Multiplayer/Rooms/Playlist/ScoresController.php index 54a50a184f9..48ca629c14a 100644 --- a/app/Http/Controllers/Multiplayer/Rooms/Playlist/ScoresController.php +++ b/app/Http/Controllers/Multiplayer/Rooms/Playlist/ScoresController.php @@ -6,6 +6,7 @@ namespace App\Http\Controllers\Multiplayer\Rooms\Playlist; use App\Docs\Attributes\Limit; +use App\Docs\Attributes\SortCustom; use App\Exceptions\InvariantException; use App\Http\Controllers\Controller as BaseController; use App\Libraries\ClientCheck; @@ -44,9 +45,9 @@ public function __construct() * @urlParam playlist integer required Id of the playlist item. * * @usesCursor - * @queryParam sort [MultiplayerScoresSort](#multiplayerscoressort) parameter. */ #[Limit(50, 1, 50)] + #[SortCustom('MultiplayerScoresSort')] public function index($roomId, $playlistId) { $playlist = PlaylistItem::where('room_id', $roomId)->findOrFail($playlistId); diff --git a/app/Http/Controllers/Multiplayer/RoomsController.php b/app/Http/Controllers/Multiplayer/RoomsController.php index 62454726e6b..dcbfe3e3807 100644 --- a/app/Http/Controllers/Multiplayer/RoomsController.php +++ b/app/Http/Controllers/Multiplayer/RoomsController.php @@ -6,6 +6,7 @@ namespace App\Http\Controllers\Multiplayer; use App\Docs\Attributes\Limit; +use App\Docs\Attributes\SortCustom; use App\Exceptions\InvariantException; use App\Http\Controllers\Controller; use App\Http\Controllers\Ranking\DailyChallengeController; @@ -37,10 +38,9 @@ public function destroy($id) * * @queryParam mode Filter mode; `active` (default), `all`, `ended`, `participated`, `owned`. No-example * @queryParam season_id Season ID to return Rooms from. No-example - * @queryParam sort Sort order; `ended`, `created`. No-example * @queryParam type_group `playlists` (default) or `realtime`. No-example */ - #[Limit(250, 1, 250)] + #[Limit(250, 1, 250), SortCustom(['ended', 'created'])] public function index() { $apiVersion = api_version(); From 24db77a9cf42d734bdbd7c59bfcb37f719d79bef Mon Sep 17 00:00:00 2001 From: bakaneko Date: Thu, 15 Aug 2024 15:45:47 +0900 Subject: [PATCH 19/25] wtf --- app/Docs/Attributes/Limit.php | 1 - app/Docs/Attributes/Offset.php | 1 - app/Docs/Attributes/Page.php | 1 - app/Docs/Attributes/SortCustom.php | 1 - app/Docs/Attributes/SortId.php | 1 - 5 files changed, 5 deletions(-) diff --git a/app/Docs/Attributes/Limit.php b/app/Docs/Attributes/Limit.php index 102bec6df29..07359526971 100644 --- a/app/Docs/Attributes/Limit.php +++ b/app/Docs/Attributes/Limit.php @@ -26,4 +26,3 @@ public function __construct( parent::__construct('limit', 'integer', $description, $required, $example); } } - diff --git a/app/Docs/Attributes/Offset.php b/app/Docs/Attributes/Offset.php index f8b98707b55..2fd162ead95 100644 --- a/app/Docs/Attributes/Offset.php +++ b/app/Docs/Attributes/Offset.php @@ -21,4 +21,3 @@ public function __construct( parent::__construct('offset', 'integer', $description, $required, $example ?? 'No-example'); } } - diff --git a/app/Docs/Attributes/Page.php b/app/Docs/Attributes/Page.php index 99c7b3c65c4..64f9b869044 100644 --- a/app/Docs/Attributes/Page.php +++ b/app/Docs/Attributes/Page.php @@ -21,4 +21,3 @@ public function __construct( parent::__construct('page', 'integer', $description, $required, $example ?? 'No-example'); } } - diff --git a/app/Docs/Attributes/SortCustom.php b/app/Docs/Attributes/SortCustom.php index ba645cb93f6..e338e155ba0 100644 --- a/app/Docs/Attributes/SortCustom.php +++ b/app/Docs/Attributes/SortCustom.php @@ -32,4 +32,3 @@ public function __construct( parent::__construct('sort', 'string', $description, false, $example ?? 'No-example'); } } - diff --git a/app/Docs/Attributes/SortId.php b/app/Docs/Attributes/SortId.php index bf615aeb192..9960a381d7e 100644 --- a/app/Docs/Attributes/SortId.php +++ b/app/Docs/Attributes/SortId.php @@ -21,4 +21,3 @@ public function __construct( parent::__construct('sort', 'string', $description, $required, $example ?? 'No-example'); } } - From aec383d0ddcd2496dd76d74c34b2d4dd447cfebf Mon Sep 17 00:00:00 2001 From: bakaneko Date: Thu, 15 Aug 2024 16:08:56 +0900 Subject: [PATCH 20/25] move id_asc and id_desc to own sort type --- .../Attributes/{SortCustom.php => Sort.php} | 2 +- app/Docs/Attributes/SortId.php | 23 ------------------- .../Strategies/GetFromQueryParamAttribute.php | 6 ++--- .../BeatmapDiscussionPostsController.php | 4 ++-- .../BeatmapDiscussionsController.php | 4 ++-- .../BeatmapsetDiscussionVotesController.php | 4 ++-- app/Http/Controllers/CommentsController.php | 4 ++-- app/Http/Controllers/EventsController.php | 4 ++-- .../Controllers/Forum/TopicsController.php | 4 ++-- app/Http/Controllers/MatchesController.php | 4 ++-- .../Rooms/Playlist/ScoresController.php | 4 ++-- .../Multiplayer/RoomsController.php | 4 ++-- resources/views/docs/_structures/id_sort.md | 9 ++++++++ 13 files changed, 30 insertions(+), 46 deletions(-) rename app/Docs/Attributes/{SortCustom.php => Sort.php} (96%) delete mode 100644 app/Docs/Attributes/SortId.php create mode 100644 resources/views/docs/_structures/id_sort.md diff --git a/app/Docs/Attributes/SortCustom.php b/app/Docs/Attributes/Sort.php similarity index 96% rename from app/Docs/Attributes/SortCustom.php rename to app/Docs/Attributes/Sort.php index e338e155ba0..c925922a278 100644 --- a/app/Docs/Attributes/SortCustom.php +++ b/app/Docs/Attributes/Sort.php @@ -11,7 +11,7 @@ use Knuckles\Scribe\Attributes\GenericParam; #[Attribute(Attribute::IS_REPEATABLE | Attribute::TARGET_FUNCTION | Attribute::TARGET_METHOD | Attribute::TARGET_CLASS)] -class SortCustom extends GenericParam +class Sort extends GenericParam { public function __construct( array|string $sorts, diff --git a/app/Docs/Attributes/SortId.php b/app/Docs/Attributes/SortId.php deleted file mode 100644 index 9960a381d7e..00000000000 --- a/app/Docs/Attributes/SortId.php +++ /dev/null @@ -1,23 +0,0 @@ -. Licensed under the GNU Affero General Public License v3.0. -// See the LICENCE file in the repository root for full licence text. - -declare(strict_types=1); - -namespace App\Docs\Attributes; - -use Attribute; -use Knuckles\Scribe\Attributes\GenericParam; - -#[Attribute(Attribute::IS_REPEATABLE | Attribute::TARGET_FUNCTION | Attribute::TARGET_METHOD | Attribute::TARGET_CLASS)] -class SortId extends GenericParam -{ - public function __construct( - string $description = '`id_desc` for newest first; `id_asc` for oldest first. Defaults to `id_desc`.', - bool $required = false, - ?string $example = null, - ) { - parent::__construct('sort', 'string', $description, $required, $example ?? 'No-example'); - } -} diff --git a/app/Docs/Strategies/GetFromQueryParamAttribute.php b/app/Docs/Strategies/GetFromQueryParamAttribute.php index 8669f2f9f8a..83d7fb3e73e 100644 --- a/app/Docs/Strategies/GetFromQueryParamAttribute.php +++ b/app/Docs/Strategies/GetFromQueryParamAttribute.php @@ -10,8 +10,7 @@ use App\Docs\Attributes\Limit; use App\Docs\Attributes\Offset; use App\Docs\Attributes\Page; -use App\Docs\Attributes\SortCustom; -use App\Docs\Attributes\SortId; +use App\Docs\Attributes\Sort; use Http\Message\Authentication\QueryParam; use Knuckles\Scribe\Extracting\Strategies\GetParamsFromAttributeStrategy; @@ -22,7 +21,6 @@ class GetFromQueryParamAttribute extends GetParamsFromAttributeStrategy Offset::class, Page::class, QueryParam::class, - SortCustom::class, - SortId::class, + Sort::class, ]; } diff --git a/app/Http/Controllers/BeatmapDiscussionPostsController.php b/app/Http/Controllers/BeatmapDiscussionPostsController.php index 0c3abd81990..b3665d1728a 100644 --- a/app/Http/Controllers/BeatmapDiscussionPostsController.php +++ b/app/Http/Controllers/BeatmapDiscussionPostsController.php @@ -7,7 +7,7 @@ use App\Docs\Attributes\Limit; use App\Docs\Attributes\Page; -use App\Docs\Attributes\SortId; +use App\Docs\Attributes\Sort; use App\Exceptions\ModelNotSavedException; use App\Libraries\BeatmapsetDiscussion\Discussion; use App\Libraries\BeatmapsetDiscussion\Reply; @@ -73,7 +73,7 @@ public function destroy($id) * @queryParam user integer The `id` of the [User](#user). * @queryParam with_deleted boolean This param has no effect as api calls do not currently receive group permissions. */ - #[Limit, Page, SortId] + #[Limit, Page, Sort('IdSort')] public function index() { $bundle = new BeatmapsetDiscussionPostsBundle(request()->all()); diff --git a/app/Http/Controllers/BeatmapDiscussionsController.php b/app/Http/Controllers/BeatmapDiscussionsController.php index c7c57033482..a08dee6a440 100644 --- a/app/Http/Controllers/BeatmapDiscussionsController.php +++ b/app/Http/Controllers/BeatmapDiscussionsController.php @@ -7,7 +7,7 @@ use App\Docs\Attributes\Limit; use App\Docs\Attributes\Page; -use App\Docs\Attributes\SortId; +use App\Docs\Attributes\Sort; use App\Exceptions\ModelNotSavedException; use App\Libraries\BeatmapsetDiscussion\Review; use App\Libraries\BeatmapsetDiscussionsBundle; @@ -101,7 +101,7 @@ public function destroy($id) * @queryParam user integer The `id` of the [User](#user). * @queryParam with_deleted boolean This param has no effect as api calls do not currently receive group permissions. No-example */ - #[Limit, Page, SortId] + #[Limit, Page, Sort('IdSort')] public function index() { $bundle = new BeatmapsetDiscussionsBundle(request()->all()); diff --git a/app/Http/Controllers/BeatmapsetDiscussionVotesController.php b/app/Http/Controllers/BeatmapsetDiscussionVotesController.php index cd8cbc03454..d28e2ec7af8 100644 --- a/app/Http/Controllers/BeatmapsetDiscussionVotesController.php +++ b/app/Http/Controllers/BeatmapsetDiscussionVotesController.php @@ -7,7 +7,7 @@ use App\Docs\Attributes\Limit; use App\Docs\Attributes\Page; -use App\Docs\Attributes\SortId; +use App\Docs\Attributes\Sort; use App\Libraries\BeatmapsetDiscussionVotesBundle; /** @@ -49,7 +49,7 @@ public function __construct() * @queryParam user integer The `id` of the [User](#user) giving the votes. * @queryParam with_deleted boolean This param has no effect as api calls do not currently receive group permissions. No-example */ - #[Limit, Page, SortId] + #[Limit, Page, Sort('IdSort')] public function index() { $bundle = new BeatmapsetDiscussionVotesBundle(request()->all()); diff --git a/app/Http/Controllers/CommentsController.php b/app/Http/Controllers/CommentsController.php index 9cb3befc969..cf6b05188ae 100644 --- a/app/Http/Controllers/CommentsController.php +++ b/app/Http/Controllers/CommentsController.php @@ -5,7 +5,7 @@ namespace App\Http\Controllers; -use App\Docs\Attributes\SortCustom; +use App\Docs\Attributes\Sort; use App\Exceptions\ModelNotSavedException; use App\Jobs\Notifications\CommentNew; use App\Libraries\CommentBundle; @@ -77,7 +77,7 @@ public function destroy($id) * @queryParam cursor Pagination option. See [CommentSort](#commentsort) for detail. The format follows [Cursor](#cursor) except it's not currently included in the response. No-example * @queryParam parent_id integer Limit to comments which are reply to the specified id. Specify 0 to get top level comments. Example: 1 */ - #[SortCustom('CommentSort', 'Defaults to `new` for guests and user-specified default when authenticated.', 'new')] + #[Sort('CommentSort', 'Defaults to `new` for guests and user-specified default when authenticated.', 'new')] public function index() { $params = request()->all(); diff --git a/app/Http/Controllers/EventsController.php b/app/Http/Controllers/EventsController.php index 3573e166528..fd22cb0bf76 100644 --- a/app/Http/Controllers/EventsController.php +++ b/app/Http/Controllers/EventsController.php @@ -7,7 +7,7 @@ namespace App\Http\Controllers; -use App\Docs\Attributes\SortId; +use App\Docs\Attributes\Sort; use App\Models\Event; /** @@ -52,7 +52,7 @@ public function __construct() * cursor_string: "eyJldmVudF9pZCI6OH0" * } */ - #[SortId] + #[Sort('IdSort')] public function index() { $params = request()->all(); diff --git a/app/Http/Controllers/Forum/TopicsController.php b/app/Http/Controllers/Forum/TopicsController.php index 6647045de02..06850356903 100644 --- a/app/Http/Controllers/Forum/TopicsController.php +++ b/app/Http/Controllers/Forum/TopicsController.php @@ -6,7 +6,7 @@ namespace App\Http\Controllers\Forum; use App\Docs\Attributes\Limit; -use App\Docs\Attributes\SortId; +use App\Docs\Attributes\Sort; use App\Exceptions\ModelNotSavedException; use App\Jobs\Notifications\ForumTopicReply; use App\Libraries\NewForumTopic; @@ -314,7 +314,7 @@ public function reply($id) * "sort": "id_asc" * } */ - #[Limit(20, 1, 50, 'Maximum number of posts to be returned'), SortId] + #[Limit(20, 1, 50, 'Maximum number of posts to be returned'), Sort('IdSort')] public function show($id) { $topic = Topic::with(['forum'])->withTrashed()->findOrFail($id); diff --git a/app/Http/Controllers/MatchesController.php b/app/Http/Controllers/MatchesController.php index 7dfec57b866..e3889338f60 100644 --- a/app/Http/Controllers/MatchesController.php +++ b/app/Http/Controllers/MatchesController.php @@ -6,7 +6,7 @@ namespace App\Http\Controllers; use App\Docs\Attributes\Limit; -use App\Docs\Attributes\SortId; +use App\Docs\Attributes\Sort; use App\Models\LegacyMatch\LegacyMatch; use App\Models\User; use App\Transformers\LegacyMatch\EventTransformer; @@ -60,7 +60,7 @@ public function __construct() * "cursor_string": "eyJtYXRjaF9pZCI6MTE0NDI4Njg1fQ" * } */ - #[Limit(50, 1, 50), SortId] + #[Limit(50, 1, 50), Sort('IdSort')] public function index() { $params = request()->all(); diff --git a/app/Http/Controllers/Multiplayer/Rooms/Playlist/ScoresController.php b/app/Http/Controllers/Multiplayer/Rooms/Playlist/ScoresController.php index 48ca629c14a..4ec9714293d 100644 --- a/app/Http/Controllers/Multiplayer/Rooms/Playlist/ScoresController.php +++ b/app/Http/Controllers/Multiplayer/Rooms/Playlist/ScoresController.php @@ -6,7 +6,7 @@ namespace App\Http\Controllers\Multiplayer\Rooms\Playlist; use App\Docs\Attributes\Limit; -use App\Docs\Attributes\SortCustom; +use App\Docs\Attributes\Sort; use App\Exceptions\InvariantException; use App\Http\Controllers\Controller as BaseController; use App\Libraries\ClientCheck; @@ -47,7 +47,7 @@ public function __construct() * @usesCursor */ #[Limit(50, 1, 50)] - #[SortCustom('MultiplayerScoresSort')] + #[Sort('MultiplayerScoresSort')] public function index($roomId, $playlistId) { $playlist = PlaylistItem::where('room_id', $roomId)->findOrFail($playlistId); diff --git a/app/Http/Controllers/Multiplayer/RoomsController.php b/app/Http/Controllers/Multiplayer/RoomsController.php index dcbfe3e3807..0072a766c29 100644 --- a/app/Http/Controllers/Multiplayer/RoomsController.php +++ b/app/Http/Controllers/Multiplayer/RoomsController.php @@ -6,7 +6,7 @@ namespace App\Http\Controllers\Multiplayer; use App\Docs\Attributes\Limit; -use App\Docs\Attributes\SortCustom; +use App\Docs\Attributes\Sort; use App\Exceptions\InvariantException; use App\Http\Controllers\Controller; use App\Http\Controllers\Ranking\DailyChallengeController; @@ -40,7 +40,7 @@ public function destroy($id) * @queryParam season_id Season ID to return Rooms from. No-example * @queryParam type_group `playlists` (default) or `realtime`. No-example */ - #[Limit(250, 1, 250), SortCustom(['ended', 'created'])] + #[Limit(250, 1, 250), Sort(['ended', 'created'])] public function index() { $apiVersion = api_version(); diff --git a/resources/views/docs/_structures/id_sort.md b/resources/views/docs/_structures/id_sort.md new file mode 100644 index 00000000000..4760b96f4b3 --- /dev/null +++ b/resources/views/docs/_structures/id_sort.md @@ -0,0 +1,9 @@ +## IdSort + +Available sort types are `id_asc`, `id_desc`. + +Name | Description +------- | ---------------------------- +id_asc | Sort by oldest first. +id_desc | Sort by newest first. + From ed0aa52f897e43e5906528420abe51282c7d3996 Mon Sep 17 00:00:00 2001 From: bakaneko Date: Fri, 16 Aug 2024 08:56:31 +0900 Subject: [PATCH 21/25] all with_deleted should have no example (because it does nothing for api) --- app/Http/Controllers/BeatmapDiscussionPostsController.php | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/app/Http/Controllers/BeatmapDiscussionPostsController.php b/app/Http/Controllers/BeatmapDiscussionPostsController.php index b3665d1728a..fced986d793 100644 --- a/app/Http/Controllers/BeatmapDiscussionPostsController.php +++ b/app/Http/Controllers/BeatmapDiscussionPostsController.php @@ -71,7 +71,7 @@ public function destroy($id) * @queryParam beatmapset_discussion_id integer `id` of the [BeatmapsetDiscussion](#beatmapsetdiscussion). * @queryParam types string[] `first`, `reply`, `system` are the valid values. Defaults to `reply`. * @queryParam user integer The `id` of the [User](#user). - * @queryParam with_deleted boolean This param has no effect as api calls do not currently receive group permissions. + * @queryParam with_deleted boolean This param has no effect as api calls do not currently receive group permissions. No-example */ #[Limit, Page, Sort('IdSort')] public function index() From 77318fce55923f4ba0dd55040e0c1ee8ed7f63a6 Mon Sep 17 00:00:00 2001 From: bakaneko Date: Wed, 11 Sep 2024 11:13:35 +0900 Subject: [PATCH 22/25] make the model default the default instead --- app/Docs/Attributes/Limit.php | 5 +++-- app/Http/Controllers/BeatmapDiscussionPostsController.php | 2 +- app/Http/Controllers/BeatmapDiscussionsController.php | 2 +- app/Http/Controllers/BeatmapsetDiscussionVotesController.php | 2 +- app/Http/Controllers/Chat/Channels/MessagesController.php | 2 +- app/Http/Controllers/Forum/TopicsController.php | 2 +- app/Http/Controllers/MatchesController.php | 2 +- .../Multiplayer/Rooms/Playlist/ScoresController.php | 2 +- 8 files changed, 10 insertions(+), 9 deletions(-) diff --git a/app/Docs/Attributes/Limit.php b/app/Docs/Attributes/Limit.php index 07359526971..62c42906fbe 100644 --- a/app/Docs/Attributes/Limit.php +++ b/app/Docs/Attributes/Limit.php @@ -7,6 +7,7 @@ namespace App\Docs\Attributes; +use App\Models\Model; use Attribute; use Knuckles\Scribe\Attributes\GenericParam; @@ -14,8 +15,8 @@ class Limit extends GenericParam { public function __construct( - int $default = 20, // values are defaults on pagination() - int $minimum = 5, + int $default = Model::PER_PAGE, + int $minimum = 1, int $maximum = 50, string $description = 'Maximum number of results', bool $required = false, diff --git a/app/Http/Controllers/BeatmapDiscussionPostsController.php b/app/Http/Controllers/BeatmapDiscussionPostsController.php index fced986d793..98e0cf7b46b 100644 --- a/app/Http/Controllers/BeatmapDiscussionPostsController.php +++ b/app/Http/Controllers/BeatmapDiscussionPostsController.php @@ -73,7 +73,7 @@ public function destroy($id) * @queryParam user integer The `id` of the [User](#user). * @queryParam with_deleted boolean This param has no effect as api calls do not currently receive group permissions. No-example */ - #[Limit, Page, Sort('IdSort')] + #[Limit(20, 5), Page, Sort('IdSort')] public function index() { $bundle = new BeatmapsetDiscussionPostsBundle(request()->all()); diff --git a/app/Http/Controllers/BeatmapDiscussionsController.php b/app/Http/Controllers/BeatmapDiscussionsController.php index a08dee6a440..185bb9f1c98 100644 --- a/app/Http/Controllers/BeatmapDiscussionsController.php +++ b/app/Http/Controllers/BeatmapDiscussionsController.php @@ -101,7 +101,7 @@ public function destroy($id) * @queryParam user integer The `id` of the [User](#user). * @queryParam with_deleted boolean This param has no effect as api calls do not currently receive group permissions. No-example */ - #[Limit, Page, Sort('IdSort')] + #[Limit(20, 5), Page, Sort('IdSort')] public function index() { $bundle = new BeatmapsetDiscussionsBundle(request()->all()); diff --git a/app/Http/Controllers/BeatmapsetDiscussionVotesController.php b/app/Http/Controllers/BeatmapsetDiscussionVotesController.php index d28e2ec7af8..503068d68c5 100644 --- a/app/Http/Controllers/BeatmapsetDiscussionVotesController.php +++ b/app/Http/Controllers/BeatmapsetDiscussionVotesController.php @@ -49,7 +49,7 @@ public function __construct() * @queryParam user integer The `id` of the [User](#user) giving the votes. * @queryParam with_deleted boolean This param has no effect as api calls do not currently receive group permissions. No-example */ - #[Limit, Page, Sort('IdSort')] + #[Limit(20, 5), Page, Sort('IdSort')] public function index() { $bundle = new BeatmapsetDiscussionVotesBundle(request()->all()); diff --git a/app/Http/Controllers/Chat/Channels/MessagesController.php b/app/Http/Controllers/Chat/Channels/MessagesController.php index 30e9e861e74..9ba4574a0e5 100644 --- a/app/Http/Controllers/Chat/Channels/MessagesController.php +++ b/app/Http/Controllers/Chat/Channels/MessagesController.php @@ -82,7 +82,7 @@ public function __construct() * } * ] */ - #[Limit(50, 1, 50)] + #[Limit] public function index($channelId) { [ diff --git a/app/Http/Controllers/Forum/TopicsController.php b/app/Http/Controllers/Forum/TopicsController.php index 06850356903..c9d7f872136 100644 --- a/app/Http/Controllers/Forum/TopicsController.php +++ b/app/Http/Controllers/Forum/TopicsController.php @@ -314,7 +314,7 @@ public function reply($id) * "sort": "id_asc" * } */ - #[Limit(20, 1, 50, 'Maximum number of posts to be returned'), Sort('IdSort')] + #[Limit(description: 'Maximum number of posts to be returned'), Sort('IdSort')] public function show($id) { $topic = Topic::with(['forum'])->withTrashed()->findOrFail($id); diff --git a/app/Http/Controllers/MatchesController.php b/app/Http/Controllers/MatchesController.php index e3889338f60..6c16c69e9f5 100644 --- a/app/Http/Controllers/MatchesController.php +++ b/app/Http/Controllers/MatchesController.php @@ -60,7 +60,7 @@ public function __construct() * "cursor_string": "eyJtYXRjaF9pZCI6MTE0NDI4Njg1fQ" * } */ - #[Limit(50, 1, 50), Sort('IdSort')] + #[Limit, Sort('IdSort')] public function index() { $params = request()->all(); diff --git a/app/Http/Controllers/Multiplayer/Rooms/Playlist/ScoresController.php b/app/Http/Controllers/Multiplayer/Rooms/Playlist/ScoresController.php index 4ec9714293d..fbfeb0fb4d3 100644 --- a/app/Http/Controllers/Multiplayer/Rooms/Playlist/ScoresController.php +++ b/app/Http/Controllers/Multiplayer/Rooms/Playlist/ScoresController.php @@ -46,7 +46,7 @@ public function __construct() * * @usesCursor */ - #[Limit(50, 1, 50)] + #[Limit] #[Sort('MultiplayerScoresSort')] public function index($roomId, $playlistId) { From f74e31a4785d9ef6dd991a548cf78889a3b030f3 Mon Sep 17 00:00:00 2001 From: bakaneko Date: Wed, 11 Sep 2024 11:31:37 +0900 Subject: [PATCH 23/25] correct syntax for array param --- app/Http/Controllers/BeatmapsController.php | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/app/Http/Controllers/BeatmapsController.php b/app/Http/Controllers/BeatmapsController.php index ebe9af70cb4..9394f5b0c58 100644 --- a/app/Http/Controllers/BeatmapsController.php +++ b/app/Http/Controllers/BeatmapsController.php @@ -197,7 +197,7 @@ public function attributes($id) * -------- | ------------------------------------- | ----------- * beatmaps | [BeatmapExtended](#beatmapextended)[] | Includes `beatmapset` (with `ratings`), `failtimes`, and `max_combo`. * - * @queryParam ids[] integer Beatmap IDs to be returned. Specify once for each beatmap ID requested. Up to 50 beatmaps can be requested at once. Example: 1 + * @queryParam ids integer[] Beatmap IDs to be returned. Specify once for each beatmap ID requested. Up to 50 beatmaps can be requested at once. Example: [1] * * @response { * "beatmaps": [ From 65ab5e4ea63bd62777adc01f5c499b588b8b51cc Mon Sep 17 00:00:00 2001 From: bakaneko Date: Wed, 18 Sep 2024 13:19:01 +0900 Subject: [PATCH 24/25] wrong params --- app/Http/Controllers/Chat/ChannelsController.php | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/app/Http/Controllers/Chat/ChannelsController.php b/app/Http/Controllers/Chat/ChannelsController.php index f6b0ad143f2..321ff8bf01e 100644 --- a/app/Http/Controllers/Chat/ChannelsController.php +++ b/app/Http/Controllers/Chat/ChannelsController.php @@ -67,9 +67,6 @@ public function index() * * Returns the joined [ChatChannel](#chatchannel). * - * @urlParam channel integer required The `channel_id` of the [ChatChannel](#chatchannel) to mark as read. - * @urlParam message integer required The `message_id` of the [ChatMessage](#chatmessage) to mark as read up to. - * * @response { * "channel_id": 5, * "current_user_attributes": { @@ -116,7 +113,7 @@ public function join($channelId, $userId) * This endpoint will only allow the leaving of public channels initially. * * - * @urlParam channel integer required `channel_id` of the [ChatChannel](#chatchannel) leave. + * @urlParam channel integer required `channel_id` of the [ChatChannel](#chatchannel) to leave. * @urlParam user integer required `id` of the [User](#user) to leave the channel. * * @response 204 From 579027f513e1f276668da843dc101705b51dca01 Mon Sep 17 00:00:00 2001 From: bakaneko Date: Wed, 18 Sep 2024 18:00:38 +0900 Subject: [PATCH 25/25] use the const --- app/Http/Controllers/BeatmapDiscussionPostsController.php | 2 +- app/Http/Controllers/BeatmapDiscussionsController.php | 2 +- app/Http/Controllers/BeatmapsetDiscussionVotesController.php | 3 ++- 3 files changed, 4 insertions(+), 3 deletions(-) diff --git a/app/Http/Controllers/BeatmapDiscussionPostsController.php b/app/Http/Controllers/BeatmapDiscussionPostsController.php index 98e0cf7b46b..541b9e8c70d 100644 --- a/app/Http/Controllers/BeatmapDiscussionPostsController.php +++ b/app/Http/Controllers/BeatmapDiscussionPostsController.php @@ -73,7 +73,7 @@ public function destroy($id) * @queryParam user integer The `id` of the [User](#user). * @queryParam with_deleted boolean This param has no effect as api calls do not currently receive group permissions. No-example */ - #[Limit(20, 5), Page, Sort('IdSort')] + #[Limit(BeatmapDiscussionPost::PER_PAGE, 5), Page, Sort('IdSort')] public function index() { $bundle = new BeatmapsetDiscussionPostsBundle(request()->all()); diff --git a/app/Http/Controllers/BeatmapDiscussionsController.php b/app/Http/Controllers/BeatmapDiscussionsController.php index 185bb9f1c98..0474c068eb3 100644 --- a/app/Http/Controllers/BeatmapDiscussionsController.php +++ b/app/Http/Controllers/BeatmapDiscussionsController.php @@ -101,7 +101,7 @@ public function destroy($id) * @queryParam user integer The `id` of the [User](#user). * @queryParam with_deleted boolean This param has no effect as api calls do not currently receive group permissions. No-example */ - #[Limit(20, 5), Page, Sort('IdSort')] + #[Limit(BeatmapDiscussion::PER_PAGE, 5), Page, Sort('IdSort')] public function index() { $bundle = new BeatmapsetDiscussionsBundle(request()->all()); diff --git a/app/Http/Controllers/BeatmapsetDiscussionVotesController.php b/app/Http/Controllers/BeatmapsetDiscussionVotesController.php index 503068d68c5..e1a9df09312 100644 --- a/app/Http/Controllers/BeatmapsetDiscussionVotesController.php +++ b/app/Http/Controllers/BeatmapsetDiscussionVotesController.php @@ -9,6 +9,7 @@ use App\Docs\Attributes\Page; use App\Docs\Attributes\Sort; use App\Libraries\BeatmapsetDiscussionVotesBundle; +use App\Models\BeatmapDiscussionVote; /** * @group Beatmapset Discussions @@ -49,7 +50,7 @@ public function __construct() * @queryParam user integer The `id` of the [User](#user) giving the votes. * @queryParam with_deleted boolean This param has no effect as api calls do not currently receive group permissions. No-example */ - #[Limit(20, 5), Page, Sort('IdSort')] + #[Limit(BeatmapDiscussionVote::PER_PAGE, 5), Page, Sort('IdSort')] public function index() { $bundle = new BeatmapsetDiscussionVotesBundle(request()->all());