From 002cd75b4aa6af0bea22e405d7b9d4bdeac50ce5 Mon Sep 17 00:00:00 2001 From: Vincent Amstoutz Date: Thu, 3 Oct 2024 11:47:36 +0200 Subject: [PATCH] Refactor GraphQL documentation for clarity and accuracy. Updated terminology from "stages" to "providers and processors" for better clarity. Removed redundant sections to streamline information on custom mutations and configuration examples. --- core/extending.md | 3 +- core/graphql.md | 182 +++------------------------------------------- 2 files changed, 12 insertions(+), 173 deletions(-) diff --git a/core/extending.md b/core/extending.md index d0b5a082b10..822999b35bd 100644 --- a/core/extending.md +++ b/core/extending.md @@ -68,7 +68,8 @@ When using Symfony, the access checker provider is used at three different stage Here is an example of the decoration of the RespondProcessor: -Starts by creating your `CustomRespondProcessor`: +Starts by creating your `CustomRespondProcessor`: + ```php - -```php - ['type' => 'ID!']] - ), - new Mutation( - name: 'withCustomArgsMutation', - resolver: BookMutationResolver::class, - args: [ - 'sendMail' => [ - 'type' => 'Boolean!', - 'description' => 'Send a mail?' - ] - ] - ), - new Mutation( - name: 'disabledStagesMutation', - resolver: BookMutationResolver::class, - deserialize: false, - write: false - ) - ] -)] -class Book -{ - // ... -} -``` - -```yaml -#The YAML syntax is only supported for Symfony -resources: - App\Entity\Book: - graphQlOperations: - - class: ApiPlatform\Metadata\GraphQl\Query - - class: ApiPlatform\Metadata\GraphQl\QueryCollection - - class: ApiPlatform\Metadata\GraphQl\Mutation - name: create - - class: ApiPlatform\Metadata\GraphQl\Mutation - name: update - - class: ApiPlatform\Metadata\GraphQl\Mutation - name: delete - - - class: ApiPlatform\Metadata\GraphQl\Mutation - name: mutation - resolver: App\Resolver\BookMutationResolver - extraArgs: - id: - type: 'ID!' - - class: ApiPlatform\Metadata\GraphQl\Mutation - name: withCustomArgsMutation - resolver: App\Resolver\BookMutationResolver - args: - sendMail: - type: 'Boolean!' - description: 'Send a mail?' - - class: ApiPlatform\Metadata\GraphQl\Mutation - name: disabledStagesMutation - resolver: App\Resolver\BookMutationResolver - deserialize: false - write: false -``` - -```xml - - - - - - - - - - - - - - - ID! - - - - - - - - - Boolean! - Send a mail? - - - - - - - - -``` - - - Note that you need to explicitly add the auto-generated queries and mutations if they are needed when configuring custom mutations, like it's done for the [operations](#operations). As the custom queries, you can define your own arguments if you don't want to use the default ones (extracted from your resource). @@ -884,38 +755,6 @@ You can also use the `extraArgs` property in case you need to add additional arg The arguments will be in `$context['args']['input']` of your resolvers. -Your custom mutations will be available like this: - -```graphql -{ - mutation { - mutationBook(input: {id: "/books/18", title: "The Fitz and the Fool"}) { - book { - title - } - } - } - - mutation { - withCustomArgsMutationBook(input: {sendMail: true, clientMutationId: "myId"}) { - book { - title - } - clientMutationId - } - } - - mutation { - disabledStagesMutationBook(input: {title: "The Fitz and the Fool"}) { - book { - title - } - clientMutationId - } - } -} -``` - ## Subscriptions Subscriptions are an [RFC](https://github.com/graphql/graphql-spec/blob/master/rfcs/Subscriptions.md#rfc-graphql-subscriptions) to allow a client to receive pushed realtime data from the server. @@ -1043,9 +882,9 @@ See the [Extending API Platform](extending.md) documentation for more informatio ### Disabling system providers and processors -If you need to, you can disable some stages done by the resolvers, for instance if you don't want your data to be validated. +If you need to, you can disable some states providers and state processors done by the resolvers, for instance if you don't want your data to be validated. -The following table lists the stages you can disable in your resource configuration. +The following table lists the system states providers and states processors you can disable in your resource configuration. | Attribute | Type | Default | Description | |----------------------------|--------|---------|-------------------------------------------| @@ -2760,8 +2599,7 @@ You can also check the documentation of [graphql-php](https://webonyx.github.io/ The big difference in API Platform is that the value is already serialized when it's received in your type class. Similarly, you would not want to denormalize your parsed value since it will be done by API Platform later. - -#### Custom Types config for Symfony +### Custom Types config for Symfony If you use autoconfiguration (the default Symfony configuration) in your application, then you are done! @@ -2781,7 +2619,7 @@ Your custom type is now registered and is available in the `TypesContainer`. To use it please [modify the extracted types](#modify-the-extracted-types) or use it directly in [custom queries](#custom-queries) or [custom mutations](#custom-mutations). -#### Custom Types config for Laravel +### Custom Types config for Laravel If you are using Laravel tag your type with: @@ -2928,7 +2766,7 @@ final class BookContextBuilder implements SerializerContextBuilderInterface } ``` -## Export the Schema in SDL +## Export the Schema in SDL > [!WARNING] > These commands are only available for API Platform with Symfony!