Better ApiDoc definitions

app/Docs/Attributes/Limit.php

@@ -0,0 +1,29 @@
+<?php
+
+// Copyright (c) ppy Pty Ltd <[email protected]>. 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 App\Models\Model;
+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 = Model::PER_PAGE,
+        int $minimum = 1,
+        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);
+    }
+}

app/Docs/Attributes/Offset.php

@@ -0,0 +1,23 @@
+<?php
+
+// Copyright (c) ppy Pty Ltd <[email protected]>. 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');
+    }
+}

app/Docs/Attributes/Page.php

@@ -0,0 +1,23 @@
+<?php
+
+// Copyright (c) ppy Pty Ltd <[email protected]>. 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');
+    }
+}

app/Docs/Attributes/Sort.php

@@ -0,0 +1,34 @@
+<?php
+
+// Copyright (c) ppy Pty Ltd <[email protected]>. 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 Sort 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');
+    }
+}

app/Docs/Strategies/GetFromQueryParamAttribute.php

@@ -0,0 +1,26 @@
+<?php
+
+// Copyright (c) ppy Pty Ltd <[email protected]>. 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 App\Docs\Attributes\Offset;
+use App\Docs\Attributes\Page;
+use App\Docs\Attributes\Sort;
+use Http\Message\Authentication\QueryParam;
+use Knuckles\Scribe\Extracting\Strategies\GetParamsFromAttributeStrategy;
+
+class GetFromQueryParamAttribute extends GetParamsFromAttributeStrategy
+{
+    protected static array $attributeNames = [
+        Limit::class,
+        Offset::class,
+        Page::class,
+        QueryParam::class,
+        Sort::class,
+    ];
+}

app/Http/Controllers/BeatmapDiscussionPostsController.php

@@ -5,6 +5,9 @@
 
 namespace App\Http\Controllers;
 
+use App\Docs\Attributes\Limit;
+use App\Docs\Attributes\Page;
+use App\Docs\Attributes\Sort;
 use App\Exceptions\ModelNotSavedException;
 use App\Libraries\BeatmapsetDiscussion\Discussion;
 use App\Libraries\BeatmapsetDiscussion\Reply;
@@ -15,6 +18,7 @@
 use App\Models\Beatmapset;
 use App\Models\BeatmapsetWatch;
 use App\Models\User;
+use Knuckles\Scribe\Attributes\QueryParam;
 
 /**
  * @group Beatmapset Discussions
@@ -63,14 +67,13 @@ 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 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. No-example
      */
+    #[Limit(BeatmapDiscussionPost::PER_PAGE, 5), Page, Sort('IdSort')]
     public function index()
     {
         $bundle = new BeatmapsetDiscussionPostsBundle(request()->all());

app/Http/Controllers/BeatmapDiscussionsController.php

@@ -5,6 +5,9 @@
 
 namespace App\Http\Controllers;
 
+use App\Docs\Attributes\Limit;
+use App\Docs\Attributes\Page;
+use App\Docs\Attributes\Sort;
 use App\Exceptions\ModelNotSavedException;
 use App\Libraries\BeatmapsetDiscussion\Review;
 use App\Libraries\BeatmapsetDiscussionsBundle;
@@ -91,17 +94,15 @@ 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. 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 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(BeatmapDiscussion::PER_PAGE, 5), Page, Sort('IdSort')]
     public function index()
     {
         $bundle = new BeatmapsetDiscussionsBundle(request()->all());

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": [
@@ -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. 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 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 mods An array of matching Mods, or none // TODO.
-     * @queryParam type Beatmap score ranking type // TODO.
+     * @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 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)
     {

app/Http/Controllers/BeatmapsetDiscussionVotesController.php

@@ -5,7 +5,11 @@
 
 namespace App\Http\Controllers;
 
+use App\Docs\Attributes\Limit;
+use App\Docs\Attributes\Page;
+use App\Docs\Attributes\Sort;
 use App\Libraries\BeatmapsetDiscussionVotesBundle;
+use App\Models\BeatmapDiscussionVote;
 
 /**
  * @group Beatmapset Discussions
@@ -39,15 +43,14 @@ 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 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 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(BeatmapDiscussionVote::PER_PAGE, 5), Page, Sort('IdSort')]
     public function index()
     {
         $bundle = new BeatmapsetDiscussionVotesBundle(request()->all());

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": [
      *     {
@@ -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)

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]
     public function index($channelId)
     {
         [

app/Http/Controllers/Chat/ChannelsController.php

@@ -113,6 +113,9 @@ public function join($channelId, $userId)
      *   This endpoint will only allow the leaving of public channels initially.
      * </aside>
      *
+     * @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
      */
     public function part($channelId, $userId)
@@ -146,6 +149,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 +196,7 @@ public function part($channelId, $userId)
      *     }
      *   ]
      * }
+     *
      */
     public function show($channelId)
     {
@@ -314,8 +320,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 <code>message_id = 12</code>, you cannot then set it backwards to <code>message_id = 10</code>. It will be rejected.
      * </aside>
      *
-     * @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
      */