The English version of quarkus.io is the official project site. Translated sites are community supported on a best-effort basis.

SmallRye GraphQL

このガイドでは、 MicroProfile GraphQL 仕様の実装である SmallRye GraphQL をQuarkusアプリケーションで使用する方法を説明します。

GraphQL の仕様のWebサイトにも記載されているように

GraphQLは、APIのためのクエリ言語であり、既存のデータを使ってそのクエリを実行するためのランタイムです。 GraphQLは、API内のデータを完全かつ理解しやすい形で提供し、クライアントが必要なものだけを要求する力を与え、時間をかけてAPIを進化させることを容易にし、強力な開発ツールを実現します。

GraphQL はもともと2012年に Facebook が開発したもので、2015年からはオープンスタンダードとなっています。

GraphQLはREST APIの仕様を置き換えるものではなく、単なる別の手段です。RESTとは異なり、GraphQL APIは以下のようにクライアントに利益をもたらす機能を持っています。

オーバーフェッチとアンダーフェッチの防止

REST APIs are server-driven fixed data responses that cannot be determined by the client. Although the client does not require all the fields the client must retrieve all the data hence Over-fetching. A client may also require multiple REST API calls according to the first call (HATEOAS) to retrieve all the data that is required thereby Under-fetching.

APIの進化

GraphQL APIはクライアントから要求されたデータを返すので、既存のAPIにフィールドや機能を追加しても、既存のクライアントに大きな変更を加えることはありません。

前提条件

このガイドを完成させるには、以下が必要です:

  • 約15分

  • IDE

  • JDK 11+ がインストールされ、 JAVA_HOME が適切に設定されていること

  • Apache Maven 3.8.1+

  • 使用したい場合、 Quarkus CLI

  • ネイティブ実行可能ファイルをビルドしたい場合、MandrelまたはGraalVM(あるいはネイティブなコンテナビルドを使用する場合はDocker)をインストールし、 適切に設定していること

アーキテクチャ

このガイドでは、 /graphql で GraphQL API を公開するシンプルな GraphQL アプリケーションを構築します。

この例は、人気のある GraphQL API にインスパイアされたものです。

ソリューション

次のセクションで紹介する手順に沿って、ステップを踏んでアプリを作成することをお勧めします。ただし、完成した例にそのまま進んでも構いません。

Gitレポジトリをクローンするか git clone https://github.com/quarkusio/quarkus-quickstarts.gitアーカイブ をダウンロードします。

ソリューションは microprofile-graphql-quickstart ディレクトリ にあります。

Mavenプロジェクトの作成

まず、新しいプロジェクトが必要です。以下のコマンドで新規プロジェクトを作成します。

CLI
quarkus create app org.acme:microprofile-graphql-quickstart \
    --extension=quarkus-smallrye-graphql \
    --no-code
cd microprofile-graphql-quickstart

Gradleプロジェクトを作成するには、 --gradle または --gradle-kotlin-dsl オプションを追加します。

Quarkus CLIのインストール方法については、Quarkus CLIガイドをご参照ください。

Maven
mvn io.quarkus.platform:quarkus-maven-plugin:2.11.1.Final:create \
    -DprojectGroupId=org.acme \
    -DprojectArtifactId=microprofile-graphql-quickstart \
    -Dextensions="quarkus-smallrye-graphql" \
    -DnoCode
cd microprofile-graphql-quickstart

Gradleプロジェクトを作成するには、 -DbuildTool=gradle または -DbuildTool=gradle-kotlin-dsl オプションを追加します。

このコマンドは、 smallrye-graphql エクステンションをインポートした Maven プロジェクトを生成します。

すでにQuarkusプロジェクトが設定されている場合は、プロジェクトのベースディレクトリーで以下のコマンドを実行することで、プロジェクトに smallrye-graphql エクステンションを追加することができます。

CLI
quarkus extension add 'quarkus-smallrye-graphql'
Maven
./mvnw quarkus:add-extension -Dextensions="quarkus-smallrye-graphql"
Gradle
./gradlew addExtension --extensions="quarkus-smallrye-graphql"

これにより、ビルドファイルに以下が追加されます:

pom.xml
<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-smallrye-graphql</artifactId>
</dependency>
build.gradle
implementation("io.quarkus:quarkus-smallrye-graphql")

アプリケーションの準備: GraphQL API

このセクションでは、GraphQL APIの作成を開始します。

First, create the following entities representing a film from a galaxy far, far away:

package org.acme.microprofile.graphql;

public class Film {

    public String title;
    public Integer episodeID;
    public String director;
    public LocalDate releaseDate;

}

public class Hero {

    public String name;
    public String surname;
    public Double height;
    public Integer mass;
    public Boolean darkSide;
    public LightSaber lightSaber;
    public List<Integer> episodeIds = new ArrayList<>();

}

enum LightSaber {
    RED, BLUE, GREEN
}
For readability we use classes with public fields, but classes with private fields with public getters and setters will also work.

先ほど作成したクラスは、クライアントがアクセス可能なデータ(オブジェクト、フィールド、リレーションシップ)のセットであるGraphQLスキーマを記述しています。

引き続き、リポジトリとして動作するCDI Beanの例を見てみましょう。

@ApplicationScoped
public class GalaxyService {

    private List<Hero> heroes = new ArrayList<>();

    private List<Film> films = new ArrayList<>();

    public GalaxyService() {

        Film aNewHope = new Film();
        aNewHope.title = "A New Hope";
        aNewHope.releaseDate = LocalDate.of(1977, Month.MAY, 25);
        aNewHope.episodeID = 4;
        aNewHope.director = "George Lucas";

        Film theEmpireStrikesBack = new Film();
        theEmpireStrikesBack.title = "The Empire Strikes Back";
        theEmpireStrikesBack.releaseDate = LocalDate.of(1980, Month.MAY, 21);
        theEmpireStrikesBack.episodeID = 5;
        theEmpireStrikesBack.director = "George Lucas";

        Film returnOfTheJedi = new Film();
        returnOfTheJedi.title = "Return Of The Jedi";
        returnOfTheJedi.releaseDate = LocalDate.of(1983, Month.MAY, 25);
        returnOfTheJedi.episodeID = 6;
        returnOfTheJedi.director = "George Lucas";

        films.add(aNewHope);
        films.add(theEmpireStrikesBack);
        films.add(returnOfTheJedi);

        Hero luke = new Hero();
        luke.name = "Luke";
        luke.surname = "Skywalker";
        luke.height = 1.7;
        luke.mass = 73;
        luke.lightSaber = LightSaber.GREEN;
        luke.darkSide = false;
        luke.episodeIds.addAll(Arrays.asList(4, 5, 6));

        Hero leia = new Hero();
        leia.name = "Leia";
        leia.surname = "Organa";
        leia.height = 1.5;
        leia.mass = 51;
        leia.darkSide = false;
        leia.episodeIds.addAll(Arrays.asList(4, 5, 6));


        Hero vader = new Hero();
        vader.name = "Darth";
        vader.surname = "Vader";
        vader.height = 1.9;
        vader.mass = 89;
        vader.darkSide = true;
        vader.lightSaber = LightSaber.RED;
        vader.episodeIds.addAll(Arrays.asList(4, 5, 6));

        heroes.add(luke);
        heroes.add(leia);
        heroes.add(vader);

    }

    public List<Film> getAllFilms() {
        return films;
    }

    public Film getFilm(int id) {
        return films.get(id);
    }

    public List<Hero> getHeroesByFilm(Film film) {
        return heroes.stream()
                .filter(hero -> hero.episodeIds.contains(film.episodeID))
                .collect(Collectors.toList());
    }

    public void addHero(Hero hero) {
        heroes.add(hero);
    }

    public Hero deleteHero(int id) {
        return heroes.remove(id);
    }

    public List<Hero> getHeroesBySurname(String surname) {
        return heroes.stream()
                .filter(hero -> hero.surname.equals(surname))
                .collect(Collectors.toList());
    }
}

それでは、最初のGraphQL APIを作成してみましょう。

org.acme.microprofile.graphql.FilmResource クラスを以下のように編集します。

@GraphQLApi (1)
public class FilmResource {

    @Inject
    GalaxyService service;

    @Query("allFilms") (2)
    @Description("Get all Films from a galaxy far far away") (3)
    public List<Film> getAllFilms() {
        return service.getAllFilms();
    }
}
1 @GraphQLApi アノテーションは、CDI BeanがGraphQLのエンドポイントになることを示しています。
2 @Query アノテーションは、このメソッドが allFilms という名前でクエリー可能であることを定義します。
3 クエリー可能なメソッドのドキュメントです。
アノテーション @Query の値はオプションで、これがない場合は暗黙のうちにメソッド名がデフォルトになります。

このようにして、最初のクエリー可能なAPIが作成されましたが、これは後に拡張されます。

起動

Launch the quarkus application in dev mode:

CLI
quarkus dev
Maven
./mvnw quarkus:dev
Gradle
./gradlew --console=plain quarkusDev

イントロスペクト

GraphQL APIの完全なスキーマは、以下を呼び出すことで取得できます。

curl http://localhost:8080/graphql/schema.graphql

サーバーは、GraphQL APIの完全なスキーマを返します。

GraphiQL UI

実験的 - MicroProfileの仕様に含まれません

GraphiQL UIは、GraphQL APIとの簡単なやり取りを可能にする素晴らしいツールです。

The Quarkus smallrye-graphql extension ships with GraphiQL and enables it by default in dev and test modes, but it can also be explicitly configured for production mode as well, by setting the quarkus.smallrye-graphql.ui.always-include configuration property to true.

GraphiQL can be accessed from http://localhost:8080/q/graphql-ui/ .

GraphQL UI

GraphQL UIのセキュリティを追加/削除する方法については Webエンドポイントの認可 のガイドをご覧ください。

GraphQL APIへのクエリー

それでは、 dev モードで展開されたGraphiQLページにアクセスしてみましょう。

以下のクエリをGraphiQLに入力し、 play ボタンを押します。

query allFilms {
  allFilms {
    title
    director
    releaseDate
    episodeID
  }
}

クエリには Film クラスのすべてのフィールドが含まれているので、レスポンスではすべてのフィールドを取得します。GraphQL APIのレスポンスはクライアントが決めるものなので、クライアントはどのフィールドを必要とするかを選択することができます。

クライアントが必要としているのは titlereleaseDate だけで、先ほどの API 呼び出しでは不要なデータを Over-fetching していたと仮定しましょう。

以下のクエリをGraphiQLに入力し、 play ボタンを押します。

query allFilms {
  allFilms {
    title
    releaseDate
  }
}

レスポンスでは、必要なフィールドのみを取得していることに注意してください。そのため、 Over-fetching を防ぐことができました。

引き続き、 FilmResource クラスに以下を追加して、GraphQL API を拡張してみましょう。

    @Query
    @Description("Get a Films from a galaxy far far away")
    public Film getFilm(@Name("filmId") int id) {
        return service.getFilm(id);
    }
@Query のアノテーションで値を除外していることに注目してください。したがって、クエリの名前は、 get を除いたメソッド名が暗黙的に設定されます。

This query will allow the client to retrieve the film by id, and the @Name annotation on the parameter changes the parameter name to filmId rather than the default id that it would be if you omit the @Name annotation.

GraphiQL に以下の内容を入力してリクエストしてください。

query getFilm {
  film(filmId: 1) {
    title
    director
    releaseDate
    episodeID
  }
}

先ほどの例では、 film というクエリメソッドの要求フィールドがそのように決定できます。このようにして、個々の映画の情報を取得することができます。

しかし、クライアントが filmId 01 の両方の映画を必要とするとします。REST APIでは、クライアントはAPIに2回コールする必要があります。したがって、クライアントは Under-fetching となります。

In GraphQL, it is possible to make multiple queries at once.

以下をGraphiQLに入力して、2つの映画を検索します。

query getFilms {
  film0: film(filmId: 0) {
    title
    director
    releaseDate
    episodeID
  }
  film1: film(filmId: 1) {
    title
    director
    releaseDate
    episodeID
  }
}

これにより、クライアントは1回のリクエストで必要なデータを取得できるようになりました。

APIの拡張

これまでは、映画のデータを取得するための GraphQL API を作成していました。今度は、クライアントが FilmHero データを取得できるようにしたいと考えています。

FilmResource のクラスに以下を追加します。

    public List<Hero> heroes(@Source Film film) { (1)
        return service.getHeroesByFilm(film);
    }
1 Film で応答するクエリに List<Hero> データを追加できるようになりました。

このメソッドを追加することで、GraphQL APIのスキーマが事実上変更されました。 スキーマが変更されたにもかかわらず、以前のクエリはそのまま動作します。 今回は、 FilmHero のデータを取得できるようにAPIを拡張しただけですから。

GraphiQLに以下のように入力して、フィルムとヒーローのデータを取得します。

query getFilmHeroes {
  film(filmId: 1) {
    title
    director
    releaseDate
    episodeID
    heroes {
      name
      height
      mass
      darkSide
      lightSaber
    }
  }
}

今や、レスポンスには映画のヒーローたちも含まれています。

バッチ処理

今回の getAllFilms のように Collection の戻り値を公開している場合は、より効率的にヒーローを取得するために、上記のバッチ形式を使用するとよいでしょう。

    public List<List<Hero>> heroes(@Source List<Film> films) { (1)
        // Here fetch all hero lists
    }
1 ここでは、映画を一括して受け取ることで、対応するヒーローを取り出すことができます。

Non blocking

Queries can be made reactive by using Uni as a return type, or adding @NonBlocking to the method:

    @Query
    @Description("Get a Films from a galaxy far far away")
    public Uni<Film> getFilm(int filmId) {
        // ...
    }

Or you can use @NonBlocking:

    @Query
    @Description("Get a Films from a galaxy far far away")
    @NonBlocking
    public Film getFilm(int filmId) {
        // ...
    }

Using Uni or @NonBlocking means that the request will be executed on Event-loop threads rather than Worker threads.

You can mix Blocking and Non-blocking in one request,

    @Query
    @Description("Get a Films from a galaxy far far away")
    @NonBlocking
    public Film getFilm(int filmId) {
        // ...
    }

    public List<Hero> heroes(@Source Film film) {
        return service.getHeroesByFilm(film);
    }

Above will fetch the film on the event-loop threads, but switch to the worker thread to fetch the heroes.

ミューテーション

ミューテーションは、データの作成、更新、削除の際に使用されます。

それでは、GraphQL APIにヒーローの追加と削除の機能を追加してみましょう。

FilmResource のクラスに以下を追加します。

    @Mutation
    public Hero createHero(Hero hero) {
        service.addHero(hero);
        return hero;
    }

    @Mutation
    public Hero deleteHero(int id) {
        return service.deleteHero(id);
    }

GraphiQL に次のように入力すると、 Hero が挿入されます。

mutation addHero {
  createHero(hero: {
      name: "Han",
      surname: "Solo"
      height: 1.85
      mass: 80
      darkSide: false
      episodeIds: [4, 5, 6]
  	}
  )
  {
    name
    surname
  }
}

このミューテーションを利用することで、私たちのサービスに Hero エンティティを作成しました。

レスポンスの中で、作成したヒーローの namesurname を取得していることに注目してください。これは mutation クエリの { } の中で、これらのフィールドをレスポンスで取得することを選択したためです。これは、クライアントが必要とするサーバー側で生成されたフィールドである可能性があります。

それでは、エントリーを削除してみましょう。

mutation DeleteHero {
  deleteHero(id :3){
    name
    surname
  }
}

createHero の mutation 法と同様に、 { } で定義されている削除したヒーローの namesurname も取得します。

サブスクリプション

Subscriptions allow you to subscribe to a query. It allows you to receive events and is using web sockets. See the GraphQL over WebSocket Protocol spec for more details.

Example: We want to know when new Heroes are being created:

    BroadcastProcessor<Hero> processor = BroadcastProcessor.create(); (1)

    @Mutation
    public Hero createHero(Hero hero) {
        service.addHero(hero);
        processor.onNext(hero); (2)
        return hero;
    }

    @Subscription
    public Multi<Hero> heroCreated(){
        return processor; (3)
    }
1 The Multi processor that will broadcast any new Heroes
2 When adding a new Hero, also broadcast it
3 Make the stream available in the schema and as a WebSocket during runtime

Any client that now connect to the /graphql WebSocket connection will receive events on new Heroes being created:

subscription ListenForNewHeroes {
  heroCreated {
    name
    surname
  }
}

フィールド別のクエリの作成

クエリは個々のフィールドに対して行うこともできます。例えば、ヒーローの名字を照会するメソッドを作ってみましょう。

FilmResource のクラスに以下を追加します。

    @Query
    public List<Hero> getHeroesWithSurname(@DefaultValue("Skywalker") String surname) {
        return service.getHeroesBySurname(surname);
    }

@DefaultValue のアノテーションを使用して、パラメータが提供されていない場合、姓の値は Skywalker になることを決定しました。

以下のクエリをGraphiQLでテストしてみましょう。

query heroWithDefaultSurname {
  heroesWithSurname{
    name
    surname
    lightSaber
  }
}
query heroWithSurnames {
  heroesWithSurname(surname: "Vader") {
    name
    surname
    lightSaber
  }
}

コンテキスト

この実験的なSmallRye固有の機能を使えば、コードのどこにいてもGraphQLリクエストの情報を得ることができます。

@Inject
Context context;

or as a parameter in your method if you are in the GraphQLApi class, for instance:

    @Query
    @Description("Get a Films from a galaxy far far away")
    public Film getFilm(Context context, int filmId) {
        // ...
    }

コンテキストオブジェクトによって、以下を取得することができます。

  • オリジナルのリクエスト(Query/Mutation)

  • 引数

  • パス

  • 選択されたフィールド

  • 任意の変数

これにより、データストアへのダウンストリームクエリを最適化することができます。

詳細は JavaDoc を参照してください。

GraphQL-Java

また、このコンテキストオブジェクトは、リーキーな抽象化を利用することで、基礎となる graphql-java の機能にフォールダウンすることを可能にします。

DataFetchingEnvironment dfe = context.unwrap(DataFetchingEnvironment.class);

また、スキーマ生成時に基盤となる graphql-java にアクセスして、独自の機能を直接追加することもできます。

public GraphQLSchema.Builder addMyOwnEnum(@Observes GraphQLSchema.Builder builder) {

    // Here add your own features directly, example adding an Enum
    GraphQLEnumType myOwnEnum = GraphQLEnumType.newEnum()
            .name("SomeEnum")
            .description("Adding some enum type")
            .value("value1")
            .value("value2").build();

    return builder.additionalType(myOwnEnum);
}

@Observer を使用することで、スキーマビルダーに何かを追加することができます。

For the Observer to work, you need to enable events. In application.properties, add the following: quarkus.smallrye-graphql.events.enabled=true.

Adapting

Adapt to Scalar

また、SmallRye特有の実験的な機能として、既存のスカラー(実装によって特定のJava型にマッピングされている)を別の型にマッピングしたり、GraphQLで通常 TypeInput を作成するような複雑なオブジェクトを既存のスカラーにマッピングしたりすることができます。

Adapting an existing Scalar to another type:

public class Movie {

    @AdaptToScalar(Scalar.Int.class)
    Long idLongThatShouldChangeToInt;

    // ....
}

Above will adapt the Long java type to an Int Scalar type, rather than the default BigInteger.

Adapting a complex object to a Scalar type:

public class Person {

    @AdaptToScalar(Scalar.String.class)
    Phone phone;

    // ....
}

これは、GraphQLで TypeInput を作成するのではなく、Stringのスカラーにマッピングされます。

上記の操作を行うためには、 Phone オブジェクトは、文字列(または Int / Date など)を受け取るコンストラクタを持つか、文字列(または Int / Date など)のセッターメソッドを持つか、 fromString (または fromInt / fromDate - スカラーの型に依存)のスタティックメソッドを持つ必要があります。

例えば、以下のようになります。

public class Phone {

    private String number;

    // Getters and setters....

    public static Phone fromString(String number) {
        Phone phone = new Phone();
        phone.setNumber(number);
        return phone;
    }
}

See more about the @AdaptToScalar feature in the JavaDoc.

Adapt with

Another option for more complex cases is to provide an Adapter. You can then do the mapping yourself in the adapter.

See more about the AdaptWith feature in the JavaDoc.

例えば、以下のようになります。

    public class Profile {
        // Map this to an email address
        @AdaptWith(AddressAdapter.class)
        public Address address;

        // other getters/setters...
    }

    public class AddressAdapter implements Adapter<EmailAddress, Address> {

        @Override
        public Address from(EmailAddress email) {
            Address a = new Address();
            a.addressType = AddressType.email;
            a.addLine(email.getValue());
            return a;
        }

        @Override
        public EmailAddress to(Address address) {
            if (address != null && address.addressType != null && address.addressType.equals(AddressType.email)) {
                return new EmailAddress(address.lines.get(0));
            }
            return null;
        }
    }
@JsonbTypeAdapter is also supported.

Built-in support for Maps

By default, due to the fact that maps are hard to model in a schema (as the keys and values can be dynamic at runtime) GraphQL does not support maps by default. Using the above adaption, Map support is added for Quarkus and are mapped to an Entry<Key,Value> with an optional key parameter. This allows you to return a map, and optionally query it by key.

Example:

    @Query
    public Map<ISO6391, Language> language() {
        return languageService.getLanguages();
    }

    public enum ISO6391 {
        af,
        en,
        de,
        fr
    }

    public class Language {
        private ISO6391 iso6391;
        private String nativeName;
        private String enName;
        private String please;
        private String thankyou;

        // Getters & Setters
    }
The key and value object can be any of Enum, Scalar or Complex object

You can now query the whole map with all the fields:

{
  language{
    key
    value {
      enName
      iso6391
      nativeName
      please
      thankyou
    }
  }
}

This will return a result like this for example:

{
  "data": {
    "language": [
      {
        "key": "fr",
        "value": {
          "enName": "french",
          "iso6391": "fr",
          "nativeName": "français",
          "please": "s'il te plaît",
          "thankyou": "merci"
        }
      },
      {
        "key": "af",
        "value": {
          "enName": "afrikaans",
          "iso6391": "af",
          "nativeName": "afrikaans",
          "please": "asseblief",
          "thankyou": "dankie"
        }
      },
      {
        "key": "de",
        "value": {
          "enName": "german",
          "iso6391": "de",
          "nativeName": "deutsch",
          "please": "bitte",
          "thankyou": "danke dir"
        }
      },
      {
        "key": "en",
        "value": {
          "enName": "english",
          "iso6391": "en",
          "nativeName": "english",
          "please": "please",
          "thankyou": "thank you"
        }
      }
    ]
  }
}

You can also query by key

{
  language (key:af){
    value {
      please
      thankyou
    }
  }
}

That will return only that value in the map:

{
  "data": {
    "language": [
      {
        "value": {
          "please": "asseblief",
          "thankyou": "dankie"
        }
      }
    ]
  }
}
The default map adapter can to overridden with our own implementation.

エラーコード

(SmallRye特有の) @ErrorCode を使用することで、GraphQLレスポンスのエラー出力にエラーコードを追加することができます。

@ErrorCode("some-business-error-code")
public class SomeBusinessException extends RuntimeException {
    // ...
}

SomeBusinessException が発生した場合、エラー出力にはエラーコードが表示されます。

{
    "errors": [
        {
            "message": "Unexpected failure in the system. Jarvis is working to fix it.",
            "locations": [
                {
                    "line": 2,
                    "column": 3
                }
            ],
            "path": [
                "annotatedCustomBusinessException"
            ],
            "extensions": {
                "exception": "io.smallrye.graphql.test.apps.error.api.ErrorApi$AnnotatedCustomBusinessException",
                "classification": "DataFetchingException",
                "code": "some-business-error-code" (1)
            }
        }
    ],
    "data": {
        ...
    }
}
1 エラーコード

その他の注意事項

If you are using the smallrye-graphql extension and the micrometer metrics extension is present and metrics are enabled, you may encounter a java.lang.NoClassDefFoundError as some versions of the smallrye-graphql extension have runtime requirements on the Microprofile Metrics API. Add the following MicroProfile Metrics API dependency to resolve the issue:

pom.xml
<dependency>
    <groupId>org.eclipse.microprofile.metrics</groupId>
    <artifactId>microprofile-metrics-api</artifactId>
</dependency>
build.gradle
implementation("org.eclipse.microprofile.metrics:microprofile-metrics-api")

まとめ

SmallRye GraphQL は、クライアントが Over-fetchingUnder-fetching を防ぐために必要なデータを正確に取得することを可能にします。

GraphQL APIは、以前のクエリを壊すことなく拡張することができ、API evolution を容易にすることができます。

設定リファレンス

ビルド時に固定される設定プロパティ - それ以外の設定プロパティは実行時に上書き可能

Configuration property

タイプ

デフォルト

The rootPath under which queries will be served. Default to graphql By default, this value will be resolved as a path relative to ${quarkus.http.root-path}.

Environment variable: QUARKUS_SMALLRYE_GRAPHQL_ROOT_PATH

string

graphql

Enable metrics. By default, this is false. If set to true, a metrics extension is required.

Environment variable: QUARKUS_SMALLRYE_GRAPHQL_METRICS_ENABLED

boolean

Enable tracing. By default, this will be enabled if the tracing extension is added.

Environment variable: QUARKUS_SMALLRYE_GRAPHQL_TRACING_ENABLED

boolean

Enable validation. By default, this will be enabled if the Hibernate Validator extension is added.

Environment variable: QUARKUS_SMALLRYE_GRAPHQL_VALIDATION_ENABLED

boolean

Enable eventing. Allow you to receive events on bootstrap and execution.

Environment variable: QUARKUS_SMALLRYE_GRAPHQL_EVENTS_ENABLED

boolean

false

Enable non-blocking support. Default is true.

Environment variable: QUARKUS_SMALLRYE_GRAPHQL_NONBLOCKING_ENABLED

boolean

Enable GET Requests. Allow queries via HTTP GET.

Environment variable: QUARKUS_SMALLRYE_GRAPHQL_HTTP_GET_ENABLED

boolean

Enable Query parameter on POST Requests. Allow POST request to override or supply values in a query parameter.

Environment variable: QUARKUS_SMALLRYE_GRAPHQL_HTTP_POST_QUERYPARAMETERS_ENABLED

boolean

Change the type naming strategy.

Environment variable: QUARKUS_SMALLRYE_GRAPHQL_AUTO_NAME_STRATEGY

default, merge-inner-class, full

default

List of extension fields that should be included in the error response. By default, none will be included. Examples of valid values include [exception,classification,code,description,validationErrorType,queryPath]

Environment variable: QUARKUS_SMALLRYE_GRAPHQL_ERROR_EXTENSION_FIELDS

list of string

List of Runtime Exceptions class names that should show the error message. By default, Runtime Exception messages will be hidden and a generic Server Error message will be returned.

Environment variable: QUARKUS_SMALLRYE_GRAPHQL_SHOW_RUNTIME_EXCEPTION_MESSAGE

list of string

List of Checked Exceptions class names that should hide the error message. By default, Checked Exception messages will show the exception message.

Environment variable: QUARKUS_SMALLRYE_GRAPHQL_HIDE_CHECKED_EXCEPTION_MESSAGE

list of string

The default error message that will be used for hidden exception messages. Defaults to "Server Error"

Environment variable: QUARKUS_SMALLRYE_GRAPHQL_DEFAULT_ERROR_MESSAGE

string

Print the data fetcher exception to the log file. Default true in dev and test mode, default false in prod.

Environment variable: QUARKUS_SMALLRYE_GRAPHQL_PRINT_DATA_FETCHER_EXCEPTION

boolean

Make the schema available over HTTP.

Environment variable: QUARKUS_SMALLRYE_GRAPHQL_SCHEMA_AVAILABLE

boolean

true

Include the Scalar definitions in the schema.

Environment variable: QUARKUS_SMALLRYE_GRAPHQL_SCHEMA_INCLUDE_SCALARS

boolean

false

Include the schema internal definition in the schema.

Environment variable: QUARKUS_SMALLRYE_GRAPHQL_SCHEMA_INCLUDE_SCHEMA_DEFINITION

boolean

false

Include Directives in the schema.

Environment variable: QUARKUS_SMALLRYE_GRAPHQL_SCHEMA_INCLUDE_DIRECTIVES

boolean

false

Include Introspection Types in the schema.

Environment variable: QUARKUS_SMALLRYE_GRAPHQL_SCHEMA_INCLUDE_INTROSPECTION_TYPES

boolean

false

Log the payload (and optionally variables) to System out.

Environment variable: QUARKUS_SMALLRYE_GRAPHQL_LOG_PAYLOAD

off, query-only, query-and-variables

off

Set the Field visibility.

Environment variable: QUARKUS_SMALLRYE_GRAPHQL_FIELD_VISIBILITY

string

default

Exceptions that should be unwrapped (class names).

Environment variable: QUARKUS_SMALLRYE_GRAPHQL_UNWRAP_EXCEPTIONS

list of string

Subprotocols that should be supported by the server for graphql-over-websocket use cases. Allowed subprotocols are "graphql-ws" and "graphql-transport-ws". By default, both are enabled.

Environment variable: QUARKUS_SMALLRYE_GRAPHQL_WEBSOCKET_SUBPROTOCOLS

list of string

If GraphQL UI should be enabled. By default, GraphQL UI is enabled if it is included (see always-include).

Environment variable: QUARKUS_SMALLRYE_GRAPHQL_UI_ENABLE

boolean

true

SmallRye GraphQL UI configuration

タイプ

デフォルト

The path where GraphQL UI is available. The value / is not allowed as it blocks the application from serving anything else. By default, this URL will be resolved as a path relative to ${quarkus.http.non-application-root-path}.

Environment variable: QUARKUS_SMALLRYE_GRAPHQL_UI_ROOT_PATH

string

graphql-ui

Always include the UI. By default, this will only be included in dev and test. Setting this to true will also include the UI in Prod

Environment variable: QUARKUS_SMALLRYE_GRAPHQL_UI_ALWAYS_INCLUDE

boolean

false