From 8a5b9d5e4c0fa1fb5848188b2d0cff814d3a99ca Mon Sep 17 00:00:00 2001 From: Kyrch Date: Wed, 22 Apr 2026 15:05:58 -0300 Subject: [PATCH] docs(graphql): add validation section (#134) --- docs/.vitepress/config.js | 1 + docs/graphql/guide/filtering/index.md | 52 ++++++++------------ docs/graphql/guide/getting-started/index.md | 14 ------ docs/graphql/guide/pagination/index.md | 2 +- docs/graphql/guide/relationships/index.md | 32 ++++++++++++- docs/graphql/guide/validation/index.md | 53 +++++++++++++++++++++ 6 files changed, 106 insertions(+), 48 deletions(-) create mode 100644 docs/graphql/guide/validation/index.md diff --git a/docs/.vitepress/config.js b/docs/.vitepress/config.js index 3876230..875fbc0 100644 --- a/docs/.vitepress/config.js +++ b/docs/.vitepress/config.js @@ -567,6 +567,7 @@ export default { { text: 'Filtering', link: '/graphql/guide/filtering/' }, { text: 'Sorting', link: '/graphql/guide/sorting/' }, { text: 'Relationships', link: '/graphql/guide/relationships/' }, + { text: 'Validation', link: '/graphql/guide/validation' }, ], }, { diff --git a/docs/graphql/guide/filtering/index.md b/docs/graphql/guide/filtering/index.md index d3f05df..9e8668b 100644 --- a/docs/graphql/guide/filtering/index.md +++ b/docs/graphql/guide/filtering/index.md @@ -6,19 +6,7 @@ title: Filtering --- -Most queries provide filtering arguments using the AND operator. Filtering arguments are built using the `{field}_{filter}` pattern. - -## Filter Arguments - -| Name | Fields | Example | Description | -| :-----: | :--------------------------------------------: | :--------: | ----------------------------------------------- | -| Eq | String, Int, Float, Boolean, enums, DateTimeTz | name | Add an `equal` conditim to the query | -| Like | String | name_like | Add a `like` condition to the query | -| In | Int, Float, enums | id_in | Add an `in` condition to the query | -| Not in | Int, Float, enums | id_not_in | Add a `not in` condition to the query | -| Greater | Int, Float, DateTimeTz | id_greater | Add a `greater than` condition to the query | -| Lesser | Int, Float, DateTimeTz | id_lesser | Add a `less than` condition to the query | - +Most queries provide some filtering arguments using the AND operator. Filtering arguments are built using the `{field}_{filter}` case pattern. Query example: ```graphql @@ -56,8 +44,8 @@ It supports single conditions, logical operators, and nested filters. query { animePagination( where: { - field: SEASON, - operator: NE, + column: SEASON, + operator: NEQ, value: FALL } ) { @@ -81,12 +69,12 @@ query { where: { OR: [ { - field: SEASON, + column: SEASON, operator: EQ, value: WINTER, }, { - field: SEASON, + column: SEASON, operator: EQ, value: FALL, } @@ -101,19 +89,21 @@ query { } ``` -::: info -Aggregate filters (such as count/exists) do not work when combined with logical operators. -::: - ### Comparison Operators -| Value | Description | -| :-----: | :----------------------------------------------------------------------------- | -| EQ | Matches values that are exactly equal to the given value. | -| NE | Matches values that are not equal to the given value. | -| LT | Matches values less than the given value. | -| GT | Matches values greater than the given value. | -| LTE | Matches values less than or equal to the given value. | -| GTE | Matches values greater than or equal to the given value. | -| LIKE | Matches values that partially match the given pattern (using wildcard search). | -| NOTLIKE | Matches values that do not match the given pattern. | \ No newline at end of file +| Value | Description | +| :---------: | :----------------------------------------------------------------------------- | +| EQ | Matches values that are exactly equal to the given value. | +| NEQ | Matches values that are not equal to the given value. | +| LT | Matches values less than the given value. | +| GT | Matches values greater than the given value. | +| LTE | Matches values less than or equal to the given value. | +| GTE | Matches values greater than or equal to the given value. | +| LIKE | Matches values that partially match the given pattern (using wildcard search). | +| NOT_LIKE | Matches values that do not match the given pattern. | +| IN | Matches values that are within the given values. | +| NOT_IN | Matches values that are not within the given values. | +| BETWEEN | Matches values that are within a range of the given values. | +| NOT_BETWEEN | Matches values that are not within a range of the given values. | +| IS_NULL | Matches values that are null. | +| IS_NOT_NULL | Matches values that are not null. | \ No newline at end of file diff --git a/docs/graphql/guide/getting-started/index.md b/docs/graphql/guide/getting-started/index.md index c718bee..d380dd7 100644 --- a/docs/graphql/guide/getting-started/index.md +++ b/docs/graphql/guide/getting-started/index.md @@ -54,18 +54,4 @@ will return the JSON: } } } -``` - -### Singular Query - -In case you want to return a single object, there are a few types that allow it. -The following example returns the first anime with the slug hibike_euphonium. - -```graphql -query { - anime(slug: "hibike_euphonium") { - name - slug - } -} ``` \ No newline at end of file diff --git a/docs/graphql/guide/pagination/index.md b/docs/graphql/guide/pagination/index.md index c1333b2..0980e57 100644 --- a/docs/graphql/guide/pagination/index.md +++ b/docs/graphql/guide/pagination/index.md @@ -26,7 +26,7 @@ The following query ```graphql query { animePagination(first: 2, page: 1) { - paginationInfo { + paginatorInfo { count currentPage firstItem diff --git a/docs/graphql/guide/relationships/index.md b/docs/graphql/guide/relationships/index.md index 74c22d8..53a7b52 100644 --- a/docs/graphql/guide/relationships/index.md +++ b/docs/graphql/guide/relationships/index.md @@ -55,7 +55,14 @@ query { name series { pageInfo { # Pagination + hasNextPage + hasPreviousPage + startCursor + endCursor total + count + currentPage + lastPage } nodes { # Without pivot fields name @@ -79,7 +86,14 @@ will return the JSON: "name": "Hibike! Euphonium", "series": { "pageInfo": { - "total": 1 + "hasNextPage": false, + "hasPreviousPage": false, + "startCursor": "MQ==", + "endCursor": "MQ==", + "total": 1, + "count": 1, + "currentPage": 1, + "lastPage": 1 }, "nodes": [ { @@ -112,7 +126,14 @@ query { name resources { pageInfo { # Pagination + hasNextPage + hasPreviousPage + startCursor + endCursor total + count + currentPage + lastPage } nodes { # Without pivot fields link @@ -137,7 +158,14 @@ will return the JSON: "name": "Hibike! Euphonium", "resources": { "pageInfo": { - "total": 9 + "hasNextPage": false, + "hasPreviousPage": false, + "startCursor": "MQ==", + "endCursor": "OQ==", + "total": 9, + "count": 9, + "currentPage": 1, + "lastPage": 1 }, "nodes": [ { diff --git a/docs/graphql/guide/validation/index.md b/docs/graphql/guide/validation/index.md new file mode 100644 index 0000000..5de5ef6 --- /dev/null +++ b/docs/graphql/guide/validation/index.md @@ -0,0 +1,53 @@ +--- +title: Validation +--- + +# Validation + +--- + +The AnimeThemes GraphQL API follows the [GraphQL official error handling specification](https://graphql.org/learn/response/#errors). + +Whenever a validation error occurs, the API will still return an HTTP 200 status code. Instead of relying on status codes to indicate failure, errors are reported in the `errors` array within the response body. + +Validation can fail for several reasons, including: + +* An invalid query structure +* Missing required arguments +* Incorrect argument types or values + +### Example + +Consider the `findAnimeByExternalSite` query. This query requires at least one of the following arguments to function properly: `id` or `link`. + +If neither argument is provided, the API will return an HTTP 200 response with an errors array describing the validation issue, similar to the following JSON: + +```json +{ + "errors": [ + { + "message": "The id field is required when link is not present. (and 1 more error)", + "locations": [ + { + "line": 2, + "column": 2 + } + ], + "path": [ + "findAnimeByExternalSite" + ], + "extensions": { + "validation": { + "id": [ + "The id field is required when link is not present." + ], + "link": [ + "The link field is required when id is not present." + ] + } + } + } + ] +} +``` +