diff --git a/docs/README.adoc b/docs/README.adoc index 3fbaa6e6f..30e2f31a2 100644 --- a/docs/README.adoc +++ b/docs/README.adoc @@ -2,6 +2,12 @@ Documentation is built using the `mkdocs` tool. See link:https://www.mkdocs.org/user-guide/installation/[Installation guide] on how to install it. +On top of that install these 3 plugins: +``` +pip install mkdocs-material +pip install mkdocs-build-plantuml-plugin +pip install mkdocs-macros-plugin +``` Then, building the documentation locally will be as simple as running `mkdocs build` in the root of this repository (NOT in the `docs` directory) - the output should appear in the `site` directory. To fix a few things, like making links work correctly, you should serve the site diff --git a/docs/extensions.md b/docs/extensions.md new file mode 100644 index 000000000..0ed1f27c8 --- /dev/null +++ b/docs/extensions.md @@ -0,0 +1,44 @@ +# Adding extensions to GraphQL response +**SmallRye GraphQL** allows the user to add their own extensions inside the GraphQL response +which is received from the server. The `extensions` are stored next to the `data` field in the GraphQL response. + +``` json +{ + "data": { + "shirt": { + "size": "L" + } + }, + "extensions": { + "country": "Germany", + "pi": 3.1415926535 + } +} +``` + +To add extensions, you need to `@Inject` an instance of `SmallRyeContext` in your `@GraphQLApi` annotated class. +After that, you can add your own extensions via the method `addExtensions` +with its input parameters: `key : String` as an identification of the added extension. +And `value: Object` as a value of the extension. Value can be any given object that can be converted into JsonValue. + +As an example, this class below contains the query `getShirt` and during the http request, the query adds these extensions: +`{"country": "Germany", "pi": 3.1415926535}`. +These extensions will be sent back via response in the `extensions` field. +```java +import jakarta.inject.Inject; + +@GraphQLApi +public class ShirtResources { + @Inject + SmallRyeContext smallRyeContext; + + @Query + public Shirt getShirt() { + smallRyeContext.addExtensions("country", "Germany"); + smallRyeContext.addExtensions("pi", 3.1415926535); + //... + } +} +``` +> [NOTE] +> You can also use the method `setAddedExtensions(Map addedExtensions)` to set all the extensions with map instance. diff --git a/mkdocs.yml b/mkdocs.yml index 926432bda..d363a89e8 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -9,6 +9,7 @@ nav: - Directives: 'directives.md' - Federation: 'federation.md' - Custom error extensions: 'custom-error-extensions.md' + - Response extensions: 'extensions.md' - Typesafe client: - Basic usage: 'typesafe-client-usage.md' - Reactive: 'typesafe-client-reactive-types.md' diff --git a/server/implementation/src/main/java/io/smallrye/graphql/execution/context/SmallRyeContext.java b/server/implementation/src/main/java/io/smallrye/graphql/execution/context/SmallRyeContext.java index 04d0ed8c5..74305dac9 100644 --- a/server/implementation/src/main/java/io/smallrye/graphql/execution/context/SmallRyeContext.java +++ b/server/implementation/src/main/java/io/smallrye/graphql/execution/context/SmallRyeContext.java @@ -49,10 +49,21 @@ public Map getAddedExtensions() { return addedExtensions; } + /** + * Sets the entire map of extension(s) into the context. + * + * @param addedExtensions The Map object containing extension(s). + */ public void setAddedExtensions(Map addedExtensions) { this.addedExtensions = addedExtensions; } + /** + * Adds single instance of user created extension into the context. + * + * @param key The key (identification) of the extension. + * @param value The value of extension. + */ public void addExtension(String key, Object value) { addedExtensions.put(key, value); }