malhuda/jikan-rest
1
0
Fork 0
mirror of https://github.com/jikan-me/jikan-rest.git synced 2025-02-20 11:23:35 +08:00
Code Issues Actions Packages Projects Releases Wiki Activity

update docs

Browse Source
This commit is contained in:
Irfan 2022-01-02 00:54:31 +05:00
parent bfa6439206
commit 770a855a85
8 changed files with 184 additions and 278 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
app/Http/Controllers/V4DB/GenreController.php
View File

@ -84,7 +84,7 @@ class GenreController extends Controller
/**
* @OA\Get(
* path="/genres/manga",
* operationId="getAnimeGenres",
* operationId="getMangaGenres",
* tags={"genres"},
*
* @OA\Parameter(ref="#/components/parameters/page"),

59
app/Http/Controllers/V4DB/RecommendationsController.php
View File

@ -15,41 +15,17 @@ use MongoDB\BSON\UTCDateTime;
class RecommendationsController extends Controller
{
/**
* @OA\Schema(
* schema="recent recommendations",
* description="Recent Recommendations",
*
* allOf={
* @OA\Schema(ref="#/components/schemas/pagination"),
* @OA\Schema(
* @OA\Property(
* property="data",
* type="array",
* @OA\Items(
* type="object",
* anyOf={
* @OA\Schema(ref="#/components/schemas/anime recommendation"),
* @OA\Schema(ref="#/components/schemas/manga recommendation"),
* },
* ),
* ),
* ),
* }
* ),
*/
/**
* @OA\Get(
* path="/recommendations/anime",
* operationId="getAnimeRecommendations",
* operationId="getRecentAnimeRecommendations",
* tags={"recommendations"},
*
* @OA\Response(
* response="200",
* description="Returns recent anime recommendations",
* @OA\JsonContent(
* ref="#/components/schemas/recent recommendations"
* ref="#/components/schemas/recommendations"
* )
* ),
* @OA\Response(
@ -58,19 +34,6 @@ class RecommendationsController extends Controller
* ),
* ),
*
* @OA\Schema(
* schema="anime recommendation",
* description="Anime Recommendations",
* @OA\Property(
* property="anime",
* type="array",
* description="Similar Anime",
* @OA\Items(
* type="object",
* ref="#/components/schemas/mal_url",
* ),
* ),
* ),
*/
public function anime(Request $request)
{
@ -89,6 +52,7 @@ class RecommendationsController extends Controller
$results = $this->updateCache($request, $results, $response);
}
$response = (new ResultsResource(
$results->first()
))->response();
@ -103,14 +67,14 @@ class RecommendationsController extends Controller
/**
* @OA\Get(
* path="/recommendations/manga",
* operationId="getMangaRecommendations",
* operationId="getRecentMangaRecommendations",
* tags={"recommendations"},
*
* @OA\Response(
* response="200",
* description="Returns recent manga recommendations",
* @OA\JsonContent(
* ref="#/components/schemas/recent recommendations"
* ref="#/components/schemas/recommendations"
* )
* ),
* @OA\Response(
@ -119,19 +83,6 @@ class RecommendationsController extends Controller
* ),
* ),
*
* @OA\Schema(
* schema="manga recommendation",
* description="Manga Recommendations",
* @OA\Property(
* property="manga",
* type="array",
* description="Similar Manga",
* @OA\Items(
* type="object",
* ref="#/components/schemas/mal_url",
* ),
* ),
* ),
*/
public function manga(Request $request)
{

20
app/Http/Controllers/V4DB/SearchController.php
View File

@ -618,26 +618,6 @@ class SearchController extends Controller
* ),
* ),
*
* @OA\Schema(
* schema="user by id",
* description="User Meta By ID",
*
* @OA\Property(
* property="data",
* type="object",
*
* @OA\Property(
* property="url",
* type="string",
* description="MyAnimeList URL"
* ),
* @OA\Property(
* property="username",
* type="string",
* description="MyAnimeList Username"
* ),
* ),
* ),
*
*/
public function userById(Request $request, int $id)

9
app/Http/Controllers/V4DB/UserController.php
View File

@ -770,7 +770,7 @@ class UserController extends Controller
* @OA\Response(
* response="200",
* description="Returns Recent Anime Recommendations",
* @OA\JsonContent()
* @OA\JsonContent(ref="#/components/schemas/recommendations")
* ),
* @OA\Response(
* response="400",
@ -816,7 +816,7 @@ class UserController extends Controller
* @OA\Response(
* response="200",
* description="Returns user clubs",
* @OA\JsonContent()
* @OA\JsonContent(ref="#/components/schemas/user clubs")
* ),
* @OA\Response(
* response="400",
@ -848,6 +848,11 @@ class UserController extends Controller
* type="string",
* description="Club Name"
* ),
* @OA\Property(
* property="url",
* type="string",
* description="Club URL"
* ),
* ),
* ),
* ),

21
app/Http/Resources/V4/CommonResource.php
View File

@ -313,6 +313,27 @@ class CommonResource extends JsonResource
* ),
* ),
*
* @OA\Schema(
* schema="user by id",
* description="User Meta By ID",
*
* @OA\Property(
* property="data",
* type="object",
*
* @OA\Property(
* property="url",
* type="string",
* description="MyAnimeList URL"
* ),
* @OA\Property(
* property="username",
* type="string",
* description="MyAnimeList Username"
* ),
* ),
* ),
*
* @OA\Schema(
* schema="user images",
* type="object",

113
app/Http/Resources/V4/RecommendationsResource.php
View File

@ -14,50 +14,56 @@ class RecommendationsResource extends JsonResource
*
* @OA\Schema(
* schema="recommendations",
* description="Recommendations Resource",
* description="Recommendations",
*
* @OA\Property(
* property="data",
* type="array",
* allOf={
* @OA\Schema(ref="#/components/schemas/pagination"),
* @OA\Schema(
* @OA\Property(
* property="data",
* type="array",
*
* @OA\Items(
* type="object",
* @OA\Property(
* property="mal_id",
* type="integer",
* description="Recommended MyAnimeList ID"
* ),
* @OA\Property(
* property="url",
* type="string",
* description="Recommended MyAnimeList URL"
* ),
* @OA\Property(
* property="image_url",
* type="string",
* description="Recommended MyAnimeList Image URL"
* ),
* @OA\Property(
* property="recommendation_url",
* type="string",
* description="Recommendation MyAnimeList URL"
* ),
* @OA\Property(
* property="title",
* type="string",
* description="Recommended Entry Title"
* ),
* @OA\Property(
* property="recommendation_count",
* type="integer",
* description="Number of users who have recommended this entry"
* @OA\Items(
* type="object",
*
* @OA\Property(
* property="mal_id",
* type="String",
* description="MAL IDs of recommendations is both of the MAL ID's with a `-` delimiter",
* ),
*
* @OA\Property (
* property="entry",
* type="array",
* description="Array of 2 entries that are being recommended to each other",
*
* @OA\Items(
* type="object",
* anyOf={
* @OA\Schema(ref="#/components/schemas/anime meta"),
* @OA\Schema(ref="#/components/schemas/manga meta"),
* }
* ),
* ),
*
* @OA\Property (
* property="content",
* type="string",
* description="Recommendation context provided by the user",
* ),
*
* @OA\Property (
* property="user",
* type="object",
* ref="#/components/schemas/user by id",
* ),
* ),
* ),
* ),
* ),
* }
* ),
*
*
*
* @OA\Schema(
* schema="entry recommendations",
* description="Entry Recommendations Resource",
@ -68,33 +74,18 @@ class RecommendationsResource extends JsonResource
*
* @OA\Items(
* type="object",
*
* @OA\Property(
* @OA\Property (
* property="entry",
* type="object",
* type="array",
* description="Array of 2 entries that are being recommended to each other",
*
* @OA\Property(
* property="mal_id",
* type="integer",
* description="Recommended MyAnimeList ID"
* ),
* @OA\Property(
* property="url",
* type="string",
* description="Recommended MyAnimeList URL"
* ),
* @OA\Property(
* property="images",
* @OA\Items(
* type="object",
* description="Recommended MyAnimeList Image URL",
* @OA\Schema(
* ref="#/components/schemas/anime images"
* ),
* ),
* @OA\Property(
* property="title",
* type="string",
* description="Recommended Entry Title"
* anyOf={
* @OA\Schema(ref="#/components/schemas/anime meta"),
* @OA\Schema(ref="#/components/schemas/manga meta"),
* }
* ),
* ),
* @OA\Property(

14
config/swagger-lume.php
View File

@ -202,9 +202,9 @@ return [
// 'SWAGGER_LUME_CONST_HOST' => env('SWAGGER_LUME_CONST_HOST', 'http://my-default-host.com'),
'API_DESCRIPTION' => <<<EOF
[Jikan](https://jikan.moe) is an **Unofficial** MyAnimeList API.
It scrapes the website to satisfy the need for a complete API - which MyAnimeList lacks.
# Information
It scrapes the website to satisfy the need for a complete API - which MyAnimeList lacks.
⚡ Jikan is powered by it's awesome backers - 🙏 [Become a backer](https://www.patreon.com/jikan)
@ -264,18 +264,18 @@ return [
```json
{
'status': 404,
'type': 'BadResponseException',
'message': 'Resource does not exist',
'error': 'Something Happened',
'report_url': 'https://github.com...'
"status": 404,
"type": "BadResponseException",
"message": "Resource does not exist",
"error": "Something Happened",
"report_url": "https://github.com..."
}
```
| Property | Remarks |
| ---- | ---- |
| `status` | Returned HTTP Status Code |
| `type` | `Exception` generated from the API |
| `type` | Thrown Exception |
| `message` | Human-readable error message |
| `error` | Error response and trace from the API |
| `report_url` | Clicking this would redirect you to a generated GitHub issue. ℹ It's only returned on a parser error. |

224
storage/api-docs/api-docs.json
View File

@ -2,7 +2,7 @@
"openapi": "3.0.0",
"info": {
"title": "Jikan API",
"description": "[Jikan](https://jikan.moe) is an **Unofficial** MyAnimeList API.\r\n\r\n# Information\r\nIt scrapes the website to satisfy the need for a complete API - which MyAnimeList lacks.\r\n\r\n⚡ Jikan is powered by it's awesome backers - 🙏 [Become a backer](https://www.patreon.com/jikan)\r\n\r\n## Rate Limiting\r\n\r\n| Duration | Requests |\r\n|----|----|\r\n| Daily | **Unlimited** |\r\n| Per Minute | 60 requests |\r\n| Per Second | 3 requests |\r\n\r\n\r\n## JSON Notes\r\n- Any property (except arrays or objects) whose value does not exist or is undetermined, will be `null`.\r\n- Any array or object property whose value does not exist or is undetermined, will be `null`.\r\n- Any `score` property whose value does not exist or is undetermined, will be `0`.\r\n- All dates and timestamps are returned in [ISO8601](https://en.wikipedia.org/wiki/ISO_8601) format and in UTC timezone\r\n\r\n## Caching\r\nBy **CACHING**, we refer to the data parsed from MyAnimeList which is stored temporarily on our servers to provide better API performance.\r\n\r\nAll requests, by default are cached for **24 hours** except the following endpoints which have their own unique cache **Time To Live**.\r\n\r\n| Request | TTL |\r\n| ---- | ---- |\r\n| All (Default) | 24 hours |\r\n| User Anime/Manga List | 5 minutes |\r\n\r\n\r\nThe following response headers will detail cache information.\r\n\r\n| Header | Remarks |\r\n| ---- | ---- |\r\n| `Expires` | Expiry unix timestamp |\r\n\r\n\r\n## Allowed HTTP(s) requests\r\n\r\n**Jikan REST API does not provide authenticated requests for MyAnimeList.** This means you can not use it to update your anime/manga list.\r\nOnly GET requests are supported which return READ-ONLY data.\r\n\r\n## HTTP Responses\r\n\r\n| HTTP Status | Remarks |\r\n| ---- | ---- |\r\n| `200 - OK` | The request was successful |\r\n| `304 - Not Modified` | You have the latest data (Cache Validation response) |\r\n| `400 - Bad Request` | You've made an invalid request. Recheck documentation |\r\n| `404 - Not Found` | The resource was not found or MyAnimeList responded with a `404` |\r\n| `405 - Method Not Allowed` | Requested Method is not supported for resource. Only `GET` requests are allowed |\r\n| `429 - Too Many Request` | You are being rate limited by Jikan or MyAnimeList is rate-limiting our servers (specified in the error response) |\r\n| `500 - Internal Server Error` | Something is not working on our end. If you see an error response with a `report_url` URL, please click on it to open an auto-generated GitHub issue |\r\n| `503 - Service Unavailable` | The service has broke. |\r\n\r\n\r\n## JSON Error Response\r\n\r\n```json\r\n {\r\n 'status': 404,\r\n 'type': 'BadResponseException',\r\n 'message': 'Resource does not exist',\r\n 'error': 'Something Happened',\r\n 'report_url': 'https://github.com...'\r\n }\r\n```\r\n\r\n| Property | Remarks |\r\n| ---- | ---- |\r\n| `status` | Returned HTTP Status Code |\r\n| `type` | `Exception` generated from the API |\r\n| `message` | Human-readable error message |\r\n| `error` | Error response and trace from the API |\r\n| `report_url` | Clicking this would redirect you to a generated GitHub issue. ℹ It's only returned on a parser error. |\r\n\r\n\r\n## Cache Validation\r\n\r\n- All requests return a `ETag` header which is an MD5 hash of the response\r\n- You can use this hash to verify if there's new or updated content by suppliying it as the value for the `If-None-Match` in your next request header\r\n- You will get a HTTP `304 - Not Modified` response if the content has not changed\r\n- If the content has changed, you'll get a HTTP `200 - OK` response with the updated JSON response\r\n\r\n![Cache Validation](https://i.imgur.com/925ozVn.png 'Cache Validation')\r\n\r\n## Disclaimer\r\n\r\n- Jikan is not affiliated with MyAnimeList.net.\r\n- Jikan is a free, open-source API. Please use it responsibly.\r\n\r\n----\r\n\r\nBy using the API, you are agreeing to Jikan's [terms of use](https://jikan.moe/terms) policy.\r\n\r\n[v3 Documentation](https://jikan.docs.apiary.io/) - [Wrappers/SDKs](https://github.com/jikan-me/jikan#wrappers) - [Report an issue](https://github.com/jikan-me/jikan-rest/issues/new) - [Host your own server](https://github.com/jikan-me/jikan-rest)",
"description": "[Jikan](https://jikan.moe) is an **Unofficial** MyAnimeList API.\r\nIt scrapes the website to satisfy the need for a complete API - which MyAnimeList lacks.\r\n\r\n# Information\r\n\r\n⚡ Jikan is powered by it's awesome backers - 🙏 [Become a backer](https://www.patreon.com/jikan)\r\n\r\n## Rate Limiting\r\n\r\n| Duration | Requests |\r\n|----|----|\r\n| Daily | **Unlimited** |\r\n| Per Minute | 60 requests |\r\n| Per Second | 3 requests |\r\n\r\n\r\n## JSON Notes\r\n- Any property (except arrays or objects) whose value does not exist or is undetermined, will be `null`.\r\n- Any array or object property whose value does not exist or is undetermined, will be `null`.\r\n- Any `score` property whose value does not exist or is undetermined, will be `0`.\r\n- All dates and timestamps are returned in [ISO8601](https://en.wikipedia.org/wiki/ISO_8601) format and in UTC timezone\r\n\r\n## Caching\r\nBy **CACHING**, we refer to the data parsed from MyAnimeList which is stored temporarily on our servers to provide better API performance.\r\n\r\nAll requests, by default are cached for **24 hours** except the following endpoints which have their own unique cache **Time To Live**.\r\n\r\n| Request | TTL |\r\n| ---- | ---- |\r\n| All (Default) | 24 hours |\r\n| User Anime/Manga List | 5 minutes |\r\n\r\n\r\nThe following response headers will detail cache information.\r\n\r\n| Header | Remarks |\r\n| ---- | ---- |\r\n| `Expires` | Expiry unix timestamp |\r\n\r\n\r\n## Allowed HTTP(s) requests\r\n\r\n**Jikan REST API does not provide authenticated requests for MyAnimeList.** This means you can not use it to update your anime/manga list.\r\nOnly GET requests are supported which return READ-ONLY data.\r\n\r\n## HTTP Responses\r\n\r\n| HTTP Status | Remarks |\r\n| ---- | ---- |\r\n| `200 - OK` | The request was successful |\r\n| `304 - Not Modified` | You have the latest data (Cache Validation response) |\r\n| `400 - Bad Request` | You've made an invalid request. Recheck documentation |\r\n| `404 - Not Found` | The resource was not found or MyAnimeList responded with a `404` |\r\n| `405 - Method Not Allowed` | Requested Method is not supported for resource. Only `GET` requests are allowed |\r\n| `429 - Too Many Request` | You are being rate limited by Jikan or MyAnimeList is rate-limiting our servers (specified in the error response) |\r\n| `500 - Internal Server Error` | Something is not working on our end. If you see an error response with a `report_url` URL, please click on it to open an auto-generated GitHub issue |\r\n| `503 - Service Unavailable` | The service has broke. |\r\n\r\n\r\n## JSON Error Response\r\n\r\n```json\r\n {\r\n \"status\": 404,\r\n \"type\": \"BadResponseException\",\r\n \"message\": \"Resource does not exist\",\r\n \"error\": \"Something Happened\",\r\n \"report_url\": \"https://github.com...\"\r\n }\r\n```\r\n\r\n| Property | Remarks |\r\n| ---- | ---- |\r\n| `status` | Returned HTTP Status Code |\r\n| `type` | Thrown Exception |\r\n| `message` | Human-readable error message |\r\n| `error` | Error response and trace from the API |\r\n| `report_url` | Clicking this would redirect you to a generated GitHub issue. ℹ It's only returned on a parser error. |\r\n\r\n\r\n## Cache Validation\r\n\r\n- All requests return a `ETag` header which is an MD5 hash of the response\r\n- You can use this hash to verify if there's new or updated content by suppliying it as the value for the `If-None-Match` in your next request header\r\n- You will get a HTTP `304 - Not Modified` response if the content has not changed\r\n- If the content has changed, you'll get a HTTP `200 - OK` response with the updated JSON response\r\n\r\n![Cache Validation](https://i.imgur.com/925ozVn.png 'Cache Validation')\r\n\r\n## Disclaimer\r\n\r\n- Jikan is not affiliated with MyAnimeList.net.\r\n- Jikan is a free, open-source API. Please use it responsibly.\r\n\r\n----\r\n\r\nBy using the API, you are agreeing to Jikan's [terms of use](https://jikan.moe/terms) policy.\r\n\r\n[v3 Documentation](https://jikan.docs.apiary.io/) - [Wrappers/SDKs](https://github.com/jikan-me/jikan#wrappers) - [Report an issue](https://github.com/jikan-me/jikan-rest/issues/new) - [Host your own server](https://github.com/jikan-me/jikan-rest)",
"termsOfService": "https://jikan.moe/terms",
"contact": {
"name": "API Support (Discord)",
@ -888,7 +888,7 @@
"tags": [
"genres"
],
"operationId": "getAnimeGenres",
"operationId": "getMangaGenres",
"parameters": [
{
"$ref": "#/components/parameters/page"
@ -1510,14 +1510,14 @@
"tags": [
"recommendations"
],
"operationId": "getAnimeRecommendations",
"operationId": "getRecentAnimeRecommendations",
"responses": {
"200": {
"description": "Returns recent anime recommendations",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/recent recommendations"
"$ref": "#/components/schemas/recommendations"
}
}
}
@ -1533,14 +1533,14 @@
"tags": [
"recommendations"
],
"operationId": "getMangaRecommendations",
"operationId": "getRecentMangaRecommendations",
"responses": {
"200": {
"description": "Returns recent manga recommendations",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/recent recommendations"
"$ref": "#/components/schemas/recommendations"
}
}
}
@ -2733,7 +2733,9 @@
"description": "Returns Recent Anime Recommendations",
"content": {
"application/json": {
"schema": {}
"schema": {
"$ref": "#/components/schemas/recommendations"
}
}
}
},
@ -2754,7 +2756,9 @@
"description": "Returns user clubs",
"content": {
"application/json": {
"schema": {}
"schema": {
"$ref": "#/components/schemas/user clubs"
}
}
}
},
@ -3060,59 +3064,6 @@
},
"type": "object"
},
"recent recommendations": {
"description": "Recent Recommendations",
"allOf": [
{
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"anyOf": [
{
"$ref": "#/components/schemas/anime recommendation"
},
{
"$ref": "#/components/schemas/manga recommendation"
}
]
}
}
},
"type": "object"
},
{
"$ref": "#/components/schemas/pagination"
}
]
},
"anime recommendation": {
"description": "Anime Recommendations",
"properties": {
"anime": {
"description": "Similar Anime",
"type": "array",
"items": {
"$ref": "#/components/schemas/mal_url"
}
}
},
"type": "object"
},
"manga recommendation": {
"description": "Manga Recommendations",
"properties": {
"manga": {
"description": "Similar Manga",
"type": "array",
"items": {
"$ref": "#/components/schemas/mal_url"
}
}
},
"type": "object"
},
"schedules": {
"description": "Anime resources currently airing",
"allOf": [
@ -3163,25 +3114,6 @@
}
]
},
"user by id": {
"description": "User Meta By ID",
"properties": {
"data": {
"properties": {
"url": {
"description": "MyAnimeList URL",
"type": "string"
},
"username": {
"description": "MyAnimeList Username",
"type": "string"
}
},
"type": "object"
}
},
"type": "object"
},
"seasons": {
"description": "List of available seasons",
"properties": {
@ -3285,6 +3217,10 @@
"name": {
"description": "Club Name",
"type": "string"
},
"url": {
"description": "Club URL",
"type": "string"
}
},
"type": "object"
@ -4682,6 +4618,25 @@
},
"type": "object"
},
"user by id": {
"description": "User Meta By ID",
"properties": {
"data": {
"properties": {
"url": {
"description": "MyAnimeList URL",
"type": "string"
},
"username": {
"description": "MyAnimeList Username",
"type": "string"
}
},
"type": "object"
}
},
"type": "object"
},
"user images": {
"properties": {
"jpg": {
@ -6239,42 +6194,51 @@
"type": "object"
},
"recommendations": {
"description": "Recommendations Resource",
"properties": {
"data": {
"type": "array",
"items": {
"properties": {
"mal_id": {
"description": "Recommended MyAnimeList ID",
"type": "integer"
},
"url": {
"description": "Recommended MyAnimeList URL",
"type": "string"
},
"image_url": {
"description": "Recommended MyAnimeList Image URL",
"type": "string"
},
"recommendation_url": {
"description": "Recommendation MyAnimeList URL",
"type": "string"
},
"title": {
"description": "Recommended Entry Title",
"type": "string"
},
"recommendation_count": {
"description": "Number of users who have recommended this entry",
"type": "integer"
"description": "Recommendations",
"allOf": [
{
"properties": {
"data": {
"type": "array",
"items": {
"properties": {
"mal_id": {
"description": "MAL IDs of recommendations is both of the MAL ID's with a `-` delimiter",
"type": "String"
},
"entry": {
"description": "Array of 2 entries that are being recommended to each other",
"type": "array",
"items": {
"type": "object",
"anyOf": [
{
"$ref": "#/components/schemas/anime meta"
},
{
"$ref": "#/components/schemas/manga meta"
}
]
}
},
"content": {
"description": "Recommendation context provided by the user",
"type": "string"
},
"user": {
"$ref": "#/components/schemas/user by id"
}
},
"type": "object"
}
},
"type": "object"
}
}
},
"type": "object"
},
{
"$ref": "#/components/schemas/pagination"
}
},
"type": "object"
]
},
"entry recommendations": {
"description": "Entry Recommendations Resource",
@ -6284,25 +6248,19 @@
"items": {
"properties": {
"entry": {
"properties": {
"mal_id": {
"description": "Recommended MyAnimeList ID",
"type": "integer"
},
"url": {
"description": "Recommended MyAnimeList URL",
"type": "string"
},
"images": {
"description": "Recommended MyAnimeList Image URL",
"type": "object"
},
"title": {
"description": "Recommended Entry Title",
"type": "string"
}
},
"type": "object"
"description": "Array of 2 entries that are being recommended to each other",
"type": "array",
"items": {
"type": "object",
"anyOf": [
{
"$ref": "#/components/schemas/anime meta"
},
{
"$ref": "#/components/schemas/manga meta"
}
]
}
},
"url": {
"description": "Recommendation MyAnimeList URL",