From 2b67dc0d26d40953dde5f1af39c8532fccff305a Mon Sep 17 00:00:00 2001 From: Irfan Date: Sun, 23 Apr 2023 09:04:30 +0500 Subject: [PATCH] update docs --- app/Http/Controllers/V4DB/Controller.php | 42 ++++++++++ .../Controllers/V4DB/ScheduleController.php | 4 + .../Controllers/V4DB/SearchController.php | 17 ++-- .../Controllers/V4DB/SeasonController.php | 11 ++- storage/api-docs/api-docs.json | 79 +++++++++++++++++-- 5 files changed, 133 insertions(+), 20 deletions(-) diff --git a/app/Http/Controllers/V4DB/Controller.php b/app/Http/Controllers/V4DB/Controller.php index 8321550..b195c0a 100644 --- a/app/Http/Controllers/V4DB/Controller.php +++ b/app/Http/Controllers/V4DB/Controller.php @@ -11,6 +11,7 @@ use Jikan\MyAnimeList\MalClient; use JMS\Serializer\Serializer; use Laravel\Lumen\Routing\Controller as BaseController; use MongoDB\BSON\UTCDateTime; +use OpenApi\Annotations as OA; /** * Class Controller @@ -47,6 +48,47 @@ class Controller extends BaseController * ) */ + + /** + * Common parameters + * + * @OA\Parameter( + * name="page", + * in="query", + * @OA\Schema(type="integer") + * ), + * + * @OA\Parameter( + * name="limit", + * in="query", + * @OA\Schema(type="integer") + * ), + * + * @OA\Parameter( + * name="sfw", + * in="query", + * required=false, + * description="'Safe For Work'. This is a flag. When supplied it will filter out entries according to the SFW Policy. You do not need to pass a value to it. e.g usage: `?sfw`", + * @OA\Schema(type="boolean") + * ), + * + * @OA\Parameter( + * name="kids", + * in="query", + * required=false, + * description="This is a flag. When supplied it will include entries with the Kids genres in specific endpoints that filter them out by default. You do not need to pass a value to it. e.g usage: `?kids`", + * @OA\Schema(type="boolean") + * ), + * + * @OA\Parameter( + * name="unapproved", + * in="query", + * required=false, + * description="This is a flag. When supplied it will include entries which are unapproved. Unapproved entries on MyAnimeList are those that are user submitted and have not yet been approved by MAL to show up on other pages. They will have their own specifc pages and are often removed resulting in a 404 error. You do not need to pass a value to it. e.g usage: `?unapproved`", + * @OA\Schema(type="boolean") + * ), + */ + /** * @var Request */ diff --git a/app/Http/Controllers/V4DB/ScheduleController.php b/app/Http/Controllers/V4DB/ScheduleController.php index 4b2d66a..46cd5e4 100644 --- a/app/Http/Controllers/V4DB/ScheduleController.php +++ b/app/Http/Controllers/V4DB/ScheduleController.php @@ -3,6 +3,7 @@ namespace App\Http\Controllers\V4DB; use App\Dto\QueryAnimeSchedulesCommand; +use OpenApi\Annotations as OA; class ScheduleController extends Controller { @@ -38,6 +39,9 @@ class ScheduleController extends Controller * @OA\Schema(type="string",enum={"true", "false"}) * ), * + * @OA\Parameter(ref="#/components/parameters/sfw"), + * @OA\Parameter(ref="#/components/parameters/unapproved"), + * @OA\Parameter(ref="#/components/parameters/page"), * @OA\Parameter(ref="#/components/parameters/limit"), * * @OA\Response( diff --git a/app/Http/Controllers/V4DB/SearchController.php b/app/Http/Controllers/V4DB/SearchController.php index a930c6e..40b3626 100644 --- a/app/Http/Controllers/V4DB/SearchController.php +++ b/app/Http/Controllers/V4DB/SearchController.php @@ -14,21 +14,10 @@ use App\Http\Resources\V4\ResultsResource; use Illuminate\Http\Request; use Illuminate\Support\Facades\DB; use Jikan\Request\User\UsernameByIdRequest; +use OpenApi\Annotations as OA; class SearchController extends Controller { - /** - * @OA\Parameter( - * name="page", - * in="query", - * @OA\Schema(type="integer") - * ), - * @OA\Parameter( - * name="limit", - * in="query", - * @OA\Schema(type="integer") - * ), - */ /** * @OA\Get( @@ -36,6 +25,8 @@ class SearchController extends Controller * operationId="getAnimeSearch", * tags={"anime"}, * + * @OA\Parameter(ref="#/components/parameters/sfw"), + * @OA\Parameter(ref="#/components/parameters/unapproved"), * @OA\Parameter(ref="#/components/parameters/page"), * @OA\Parameter(ref="#/components/parameters/limit"), * @@ -168,6 +159,8 @@ class SearchController extends Controller * operationId="getMangaSearch", * tags={"manga"}, * + * @OA\Parameter(ref="#/components/parameters/sfw"), + * @OA\Parameter(ref="#/components/parameters/unapproved"), * @OA\Parameter(ref="#/components/parameters/page"), * @OA\Parameter(ref="#/components/parameters/limit"), * diff --git a/app/Http/Controllers/V4DB/SeasonController.php b/app/Http/Controllers/V4DB/SeasonController.php index 31601ce..a70a0cd 100644 --- a/app/Http/Controllers/V4DB/SeasonController.php +++ b/app/Http/Controllers/V4DB/SeasonController.php @@ -29,8 +29,6 @@ class SeasonController extends Controller * operationId="getSeasonNow", * tags={"seasons"}, * - * @OA\Parameter(ref="#/components/parameters/page"), - * @OA\Parameter(ref="#/components/parameters/limit"), * @OA\Parameter( * name="filter", * description="Entry types", @@ -38,6 +36,11 @@ class SeasonController extends Controller * @OA\Schema(type="string",enum={"tv","movie","ova","special","ona","music"}) * ), * + * @OA\Parameter(ref="#/components/parameters/sfw"), + * @OA\Parameter(ref="#/components/parameters/unapproved"), + * @OA\Parameter(ref="#/components/parameters/page"), + * @OA\Parameter(ref="#/components/parameters/limit"), + * * @OA\Response( * response="200", * description="Returns current seasonal anime", @@ -84,6 +87,8 @@ class SeasonController extends Controller * @OA\Schema(type="string",enum={"tv","movie","ova","special","ona","music"}) * ), * + * @OA\Parameter(ref="#/components/parameters/sfw"), + * @OA\Parameter(ref="#/components/parameters/unapproved"), * @OA\Parameter(ref="#/components/parameters/page"), * @OA\Parameter(ref="#/components/parameters/limit"), * @@ -170,6 +175,8 @@ class SeasonController extends Controller * @OA\Schema(type="string",enum={"tv","movie","ova","special","ona","music"}) * ), * + * @OA\Parameter(ref="#/components/parameters/sfw"), + * @OA\Parameter(ref="#/components/parameters/unapproved"), * @OA\Parameter(ref="#/components/parameters/page"), * @OA\Parameter(ref="#/components/parameters/limit"), * diff --git a/storage/api-docs/api-docs.json b/storage/api-docs/api-docs.json index 8fee73c..ed7e26d 100644 --- a/storage/api-docs/api-docs.json +++ b/storage/api-docs/api-docs.json @@ -2306,6 +2306,15 @@ ] } }, + { + "$ref": "#/components/parameters/sfw" + }, + { + "$ref": "#/components/parameters/unapproved" + }, + { + "$ref": "#/components/parameters/page" + }, { "$ref": "#/components/parameters/limit" } @@ -2334,6 +2343,12 @@ ], "operationId": "getAnimeSearch", "parameters": [ + { + "$ref": "#/components/parameters/sfw" + }, + { + "$ref": "#/components/parameters/unapproved" + }, { "$ref": "#/components/parameters/page" }, @@ -2486,6 +2501,12 @@ ], "operationId": "getMangaSearch", "parameters": [ + { + "$ref": "#/components/parameters/sfw" + }, + { + "$ref": "#/components/parameters/unapproved" + }, { "$ref": "#/components/parameters/page" }, @@ -2989,12 +3010,6 @@ ], "operationId": "getSeasonNow", "parameters": [ - { - "$ref": "#/components/parameters/page" - }, - { - "$ref": "#/components/parameters/limit" - }, { "name": "filter", "in": "query", @@ -3010,6 +3025,18 @@ "music" ] } + }, + { + "$ref": "#/components/parameters/sfw" + }, + { + "$ref": "#/components/parameters/unapproved" + }, + { + "$ref": "#/components/parameters/page" + }, + { + "$ref": "#/components/parameters/limit" } ], "responses": { @@ -3068,6 +3095,12 @@ ] } }, + { + "$ref": "#/components/parameters/sfw" + }, + { + "$ref": "#/components/parameters/unapproved" + }, { "$ref": "#/components/parameters/page" }, @@ -3138,6 +3171,12 @@ ] } }, + { + "$ref": "#/components/parameters/sfw" + }, + { + "$ref": "#/components/parameters/unapproved" + }, { "$ref": "#/components/parameters/page" }, @@ -4399,6 +4438,7 @@ "type": "integer" }, "url": { + "description": "MyAnimeList URL. This is the URL of the episode's video. If there is no video url, this will be null.", "type": "string", "nullable": true }, @@ -8972,6 +9012,33 @@ "schema": { "type": "integer" } + }, + "sfw": { + "name": "sfw", + "in": "query", + "description": "'Safe For Work'. This is a flag. When supplied it will filter out entries according to the SFW Policy. You do not need to pass a value to it. e.g usage: `?sfw`", + "required": false, + "schema": { + "type": "boolean" + } + }, + "kids": { + "name": "kids", + "in": "query", + "description": "This is a flag. When supplied it will include entries with the Kids genres in specific endpoints that filter them out by default. You do not need to pass a value to it. e.g usage: `?kids`", + "required": false, + "schema": { + "type": "boolean" + } + }, + "unapproved": { + "name": "unapproved", + "in": "query", + "description": "This is a flag. When supplied it will include entries which are unapproved. Unapproved entries on MyAnimeList are those that are user submitted and have not yet been approved by MAL to show up on other pages. They will have their own specifc pages and are often removed resulting in a 404 error. You do not need to pass a value to it. e.g usage: `?unapproved`", + "required": false, + "schema": { + "type": "boolean" + } } } },