diff --git a/docs/source/config.json b/docs/source/config.json index ecee636baf9..a8cbaac9a0d 100644 --- a/docs/source/config.json +++ b/docs/source/config.json @@ -61,7 +61,8 @@ "Batching operations": "/advanced/query-batching" }, "Development & Testing": { - "Overview": "/testing/overview", + "Android Studio plugin": "/testing/android-studio-plugin", + "Testing overview": "/testing/overview", "Mocking HTTP responses": "/testing/mocking-http-responses", "Mocking GraphQL responses": "/testing/mocking-graphql-responses", "Data builders": "/testing/data-builders", diff --git a/docs/source/index.md b/docs/source/index.md index 4f06beb1db5..3f522f5e716 100644 --- a/docs/source/index.md +++ b/docs/source/index.md @@ -154,7 +154,7 @@ As the code generated by Apollo Kotlin doesn't use any reflection, it can safely An experimental [plugin for Android Studio and IntelliJ](https://plugins.jetbrains.com/plugin/20645-apollo-graphql) is available to help you work with Apollo Kotlin, providing automatic code generation, integration with the [GraphQL IntelliJ Plugin](https://plugins.jetbrains.com/plugin/8097-js-graphql), navigation to GraphQL definitions, migration helpers, and more. -Installation instructions and more information can be found [here](https://github.com/apollographql/apollo-kotlin/tree/main/intellij-plugin). +Installation instructions and more information can be found [here](testing/android-studio-plugin). ## Releases diff --git a/docs/source/testing/android-studio-plugin.mdx b/docs/source/testing/android-studio-plugin.mdx new file mode 100644 index 00000000000..ee645c09b5b --- /dev/null +++ b/docs/source/testing/android-studio-plugin.mdx @@ -0,0 +1,95 @@ +--- +title: Android Studio / IntelliJ plugin +--- + +To help your day-to-day development with Apollo Kotlin, a plugin for Android Studio and IntelliJ is available. + +## Installation + +The plugin is available on the JetBrains plugin repository. To install it from the IDE, go to +Settings | Plugins | Marketplace | search for "Apollo GraphQL" | Install + +At the time of writing, the plugin is supported on: + +- IntelliJ 2022.2 and above +- Android Studio 2022.2 (Flamingo) and above + +Please check the [plugin page](https://plugins.jetbrains.com/plugin/20645-apollo-graphql) for up to date information. + +## Features + +### Automatic code generation +Automatic code generation + +The plugin automatically generates models whenever GraphQL files change. +This means you don't need to manually run `./gradlew generateApolloSources` after editing the files. + +Note: this works by running Gradle in continuous mode, and can be disabled in the plugin settings. + +### Integration with the GraphQL IntelliJ Plugin + +The plugin depends on and integrates with the [GraphQL IntelliJ Plugin](https://plugins.jetbrains.com/plugin/8097-js-graphql). +The file structure of the Apollo project is automatically contributed, so there is no need to create a `graphql.config.yml` / `.graphqlconfig` file. + +### Navigation + +#### Kotlin → GraphQL + +When editing Kotlin code, Gutter icon icons will show next to references to generated operation and fragment classes. +Clicking on them will navigate to the corresponding GraphQL definition. + +You can also go to the GraphQL definition with Cmd Click (Mac) or Ctrl Click (Windows / Linux) on an operation, field, enum, etc. + +Go to declaration + +Going to a field's **type** declaration (Cmd Shift Click on Mac, Ctrl Shift Click on Windows / Linux) will navigate to its definition in the GraphQL schema. + +Go to type declaration + +#### GraphQL → Kotlin + +You can search for code usages of a GraphQL operation, fragment, enum type/value and input type/field, with right click | Find Usages. + +Find usages + +### Unused operations / fields + +In GraphQL files, operations and fields are shown in grey if the corresponding generated code is not used in your project. + +### Migration helpers + +In the Refactor | Apollo menu, you can find helpers to migrate your project: + +- Apollo Android 2.x → Apollo Kotlin 3.x +- `compat` codegen → `operationBased` codegen +- Apollo Kotlin 3.x → Apollo Kotlin 4.x + +Note: while these helpers will automatically update your code when possible, there are some cases where this isn't possible and manual changes are required. +Please refer to the migration guides ([3.x](../migration/3.0/), [4.x](../migration/4.0/)) when upgrading. + +### Open in Apollo Sandbox + +You can open a GraphQL file in [Apollo Sandbox](https://studio.apollographql.com/sandbox/explorer) with right click | Open in | Apollo Sandbox. +This is a handy way to share operations with coworkers for instance. There, they will be able to execute the operation and see the result. + +This is also accessible from the Sandbox icon button at the top of the editor. + +### High latency fields + +If your project uses Apollo GraphOS, the plugin can use the collected metrics (["Field Insights"](https://www.apollographql.com/docs/graphos/metrics/field-usage)) and report a warning on fields that have a high latency. + +High latency in editor + +By default, fields with a latency above 100ms will be highlighted. You can change this threshold in Settings | Editor | Inspections | GraphQL | Apollo GraphOS | High latency field. + +A quick fix is available to encapsulate the field in a fragment with the [`@defer`](../fetching/defer) directive. + +For the plugin to be able to fetch the metrics, you need to configure your project with its [Apollo GraphOS API key](https://www.apollographql.com/docs/graphos/api-keys/). To do this, go to the plugin's settings: Settings | Languages & Frameworks | GraphQL | Apollo Kotlin. Here you can find the API keys table where you can add: +- API key: should start with `service:` or `user:` +- Graph ID: can be found on your graph page in Apollo Studio or is filled automatically if you provide a `service:` API key + +## Weekly snapshots + +If you wish to try the latest features, you can install the weekly snapshots. To do so, add the following repository in Settings | Plugins | ⚙️ | Manage Plugin Repositories | +: `https://raw.githubusercontent.com/apollographql/apollo-kotlin/main/intellij-plugin/snapshots/plugins.xml`. + +Then installing the plugin by searching "Apollo GraphQL" in the Marketplace will install the latest snapshot. diff --git a/docs/source/testing/images/gutter-icon.png b/docs/source/testing/images/gutter-icon.png new file mode 100644 index 00000000000..79a041c0ce2 Binary files /dev/null and b/docs/source/testing/images/gutter-icon.png differ diff --git a/docs/source/testing/images/high-latency-field-editor.png b/docs/source/testing/images/high-latency-field-editor.png new file mode 100644 index 00000000000..39539da6021 Binary files /dev/null and b/docs/source/testing/images/high-latency-field-editor.png differ diff --git a/docs/source/testing/images/ij-plugin-find-usages.webp b/docs/source/testing/images/ij-plugin-find-usages.webp new file mode 100644 index 00000000000..a96ea467131 Binary files /dev/null and b/docs/source/testing/images/ij-plugin-find-usages.webp differ diff --git a/docs/source/testing/images/ij-plugin-go-to-declaration.webp b/docs/source/testing/images/ij-plugin-go-to-declaration.webp new file mode 100644 index 00000000000..fe145d0a02c Binary files /dev/null and b/docs/source/testing/images/ij-plugin-go-to-declaration.webp differ diff --git a/docs/source/testing/images/ij-plugin-go-to-type-declaration.webp b/docs/source/testing/images/ij-plugin-go-to-type-declaration.webp new file mode 100644 index 00000000000..999760333f1 Binary files /dev/null and b/docs/source/testing/images/ij-plugin-go-to-type-declaration.webp differ diff --git a/docs/source/testing/images/ij-plugin-on-the-fly-codegen.webp b/docs/source/testing/images/ij-plugin-on-the-fly-codegen.webp new file mode 100644 index 00000000000..ffd3cf4596c Binary files /dev/null and b/docs/source/testing/images/ij-plugin-on-the-fly-codegen.webp differ diff --git a/docs/source/testing/images/open-in-sandbox.png b/docs/source/testing/images/open-in-sandbox.png new file mode 100644 index 00000000000..c23f01455fe Binary files /dev/null and b/docs/source/testing/images/open-in-sandbox.png differ diff --git a/intellij-plugin/gradle.properties b/intellij-plugin/gradle.properties index 8e9cc7219da..2bd9bf36c79 100644 --- a/intellij-plugin/gradle.properties +++ b/intellij-plugin/gradle.properties @@ -6,7 +6,7 @@ pluginId=com.apollographql.ijplugin pluginRepositoryUrl=https://github.com/apollographql/apollo-kotlin -# XXX Do update the supported versions in the README.md file when updating these values! +# XXX Do update the supported versions in the README.md, and in docs/source/testing/android-studio-plugin.mdx file when updating these values! # See https://plugins.jetbrains.com/docs/intellij/build-number-ranges.html # for insight into build numbers and IntelliJ Platform versions. pluginSinceBuild=222