Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

New formatting for GraphQL MP document #4514

Merged
merged 3 commits into from
Jul 13, 2022
Merged

New formatting for GraphQL MP document #4514

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
0f8eb3e
New formatting for GraphQL MP document.
spericas Jul 12, 2022
ffa8550
Set correct GraphQL version.
spericas Jul 12, 2022
802209e
Minor update in Examples.
spericas Jul 12, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions docs/includes/attributes.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -126,6 +126,10 @@ endif::[]
:microprofile-rest-client-spec-url: {microprofile-rest-client-base-url}/microprofile-rest-client-spec-{version-lib-microprofile-rest-client}.html
:microprofile-rest-client-javadoc-url: {microprofile-rest-client-base-url}/apidocs

:microprofile-graphql-base-url: {microprofile-base-url}/microprofile-graphql-{version-lib-microprofile-graphql}
:microprofile-graphql-spec-url: {microprofile-rest-graphql-url}/microprofile-rest-client-spec-{version-lib-microprofile-graphql}.html
:microprofile-graphql-javadoc-url: {microprofile-rest-graphql-url}/apidocs

// Jakarta versioned URLs

:jakarta-base-url: https://jakarta.ee/specifications
Expand Down
143 changes: 65 additions & 78 deletions docs/mp/graphql.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,13 +25,25 @@

include::{rootdir}/includes/mp.adoc[]

The Microprofile GraphQL APIs are an extension to xref:introduction/introduction.adoc[Helidon MP]
to allow building of applications that can expose a GraphQL endpoint.
== ToC

== Experimental
- <<Overview, Overview>>
- <<Maven Coordinates, Maven Coordinates>>
- <<API, API>>
- <<Configuration, Configuration>>
- <<Examples, Examples>>
- <<Additional Information, Additional Information>>
- <<Reference, Reference>>

== Overview

Helidon MP implements the
link:{microprofile-graphql-spec-url}[MicroProfile GraphQL specification].
This specifcation describes how applications can be built to expose an endpoint for GraphQL.
GraphQL is an open-source data query and manipulation language for APIs,
and a runtime for fulfilling data queries.
It provides an alternative to, though not necessarily a replacement for, REST.

WARNING: The Helidon GraphQL feature is currently experimental and the APIs are
subject to changes until GraphQL support is stabilized.

include::{rootdir}/includes/dependencies.adoc[]

Expand All @@ -43,57 +55,43 @@ include::{rootdir}/includes/dependencies.adoc[]
</dependency>
----

== About the MicroProfile GraphQL Specification
Helidon MP implements the MicroProfile GraphQL
link:https://github.com/eclipse/microprofile-graphql[spec] version {version-lib-microprofile-graphql}.
The spec prescribes how applications can be built to expose an endpoint for GraphQL.
GraphQL is an open-source data query and manipulation language for APIs,
and a runtime for fulfilling queries with existing data.
It provides an alternative to, though not necessarily a replacement for, REST.

For more information on GraphQL see https://graphql.org/.

== Getting Started

=== Defining your API
== API

The MicroProfile GraphQL specification defines a number of key annotations to be used when writing a GraphQL endpoint:

* `@GraphQLApi` - identifies a CDI Bean as a GraphQL Endpoint
* `@Query` - identifies a method as returning specified fields for an object or collection of entities
* `@GraphQLApi` - identifies a CDI Bean as a GraphQL endpoint
* `@Query` - identifies a method as returning one or more entities
* `@Mutation` - identifies a method which creates, deletes or updates entities

NOTE: Please see the link:https://github.com/eclipse/microprofile-graphql[Microprofile GraphQL spec] for the full list of available annotations.

For example, the following defines a GraphQL endpoint with a number of queries and mutations that work
against a fictional `CustomerService` service and `Customer` class.

[source,java]
.Simple ContactGraphQLApi
----
@ApplicationScoped
@org.eclipse.microprofile.graphql.GraphQLApi
@GraphQLApi
public class ContactGraphQLApi {

@Inject
private CustomerService customerService;

@org.eclipse.microprofile.graphql.Query
@Query
public Collection<Customer> findAllCustomers() { <1>
return customerService.getAllCustomers();
}

@org.eclipse.microprofile.graphql.Query
@Query
public Customer findCustomer(@Name("customerId") int id) { <2>
return customerService.getCustomer(id);
}

@org.eclipse.microprofile.graphql.Query
@Query
public Collection<Customer> findCustomersByName(@Name("name") String name) { <3>
return customerService.getAllCustomers(name);
}

@org.eclipse.microprofile.graphql.Mutation
@Mutation
public Contact createCustomer(@Name("customerId") int id, <4>
@Name("name") String name,
@Name("balance") float balance) {
Expand All @@ -111,14 +109,14 @@ public class customer {
}
----

<1> a query with no-arguments that will return all Customers
<2> a query that takes an argument to return a specific Customer
<3> a query that optionally takes a name and returns a collection of Customers
<4> a mutation that creates a Customer and returns the newly created Customer
<1> a query with no-arguments that will return all `Customer` s
<2> a query that takes an argument to return a specific `Customer`
<3> a query that optionally takes a name and returns a collection of `Customer` s
<4> a mutation that creates a Customer and returns the newly created `Customer`

The above would generate a GraphQL schema as shown below:
The example above would generate a GraphQL schema as shown below:
[source,graphql]
.Sample GraphQL Schema
.Sample GraphQL schema
----
type Query {
findAllCustomers: [Customer]
Expand All @@ -140,66 +138,41 @@ type Customer {
After application startup, a GraphQL schema will be generated from your annotated API classes
and POJO's and you will be able to access these via the URLs described below.

=== Creating your entry-point

As per the instructions xref:introduction/microprofile.adoc[here] ensure you have added a
`src/main/resources/META-INF/beans.xml` file, so the CDI implementation can pick up your classes.

A `Main` class is not needed, you can configure `io.helidon.microprofile.cdi.Main` as the entry point.

Optionally, you can configure a custom entry point (such as when you need custom configuration setup).

[source,java]
.Sample Entry-point
----
public class MyMain {
public static void main(String[] args) {
io.helidon.microprofile.cdi.Main.main(args);
}
}
----

=== Building your application

As part of building your application, you must create a Jandex index
using the `jandex-maven-plugin` for all API and POJO classes that are used.
using the `jandex-maven-plugin` for all API and POJO classes.

[source,xml]
.Generate Jandex index
----
<plugin>
<groupId>org.jboss.jandex</groupId>
<artifactId>jandex-maven-plugin</artifactId>
<executions>
<execution>
<id>make-index</id>
</execution>
</executions>
<groupId>org.jboss.jandex</groupId>
<artifactId>jandex-maven-plugin</artifactId>
<executions>
<execution>
<id>make-index</id>
</execution>
</executions>
</plugin>
----

== Accessing the GraphQL end-points

After starting your application you should see a message similar to the following indicating the GraphQL support is available:

[source,bash]
.Sample Startup output
----
2020.11.16 12:29:58 INFO io.helidon.common.HelidonFeatures Thread[features-thread,5,main]: Helidon MP 2.1.1-SNAPSHOT features: [CDI, Config, Fault Tolerance, GraphQL, Health, JAX-RS, Metrics, Open API, Security, Server, Tracing]
2020.11.16 12:29:58 INFO io.helidon.common.HelidonFeatures.experimental Thread[features-thread,5,main]: You are using experimental features. These APIs may change, please follow changelog!
2020.11.16 12:29:58 INFO io.helidon.common.HelidonFeatures.experimental Thread[features-thread,5,main]: Experimental feature: GraphQL (GraphQL)
----
NOTE: As per the instructions xref:introduction/microprofile.adoc[here] ensure you have added a
`src/main/resources/META-INF/beans.xml` file, so the CDI implementation can pick up your classes.

You can then use your GraphQL client via the default endpoint `http://host:port/graphql`.
=== Accessing the GraphQL endpoints

The GraphQL Schema is available via `http://host:port/graphql/schema.graphql`.
After starting your application you should see a log message indicating that GraphQL
is in the list of features. You can access the GraphQL endpoint at `http://host:port/graphql`, and
the corresponding schema at `http://host:port/graphql/schema.graphql`. See <<Configuration>> for
additional information on how to change the location of these resources.

NOTE: If you wish to use the GraphQL UI (https://github.com/graphql/graphiql) then please see the Helidon Microprofile GraphQL
link:{helidon-github-tree-url}/master/examples/microprofile/graphql[example].
If you wish to use the
link:https://github.com/graphql/graphiql[GraphQL UI] then please see the
link:{helidon-github-tree-url}/master/examples/microprofile/graphql[GraphQL MP Example].

== Configuration Options
== Configuration

=== MicroProfile GraphQL
The specification defines the following configuration options:

[cols="2,2,5"]
Expand All @@ -214,6 +187,20 @@ The specification defines the following configuration options:
|===

These configuration options are more significant that the configuration options
that can be used to configure GraphQL invocation (see below).
that can be used to configure GraphQL invocation (see below).

include::{rootdir}/includes/graphql.adoc[]

== Examples

For a complete example, see
link:{helidon-github-tree-url}/master/examples/microprofile/graphql[GraphQL MP Example].

== Additional Information

* link:http://graphql.org[GraphQL].

== Reference

* link:{microprofile-graphql-javadoc-url}[MicroProfile GraphQL Javadocs].