Skip to content

Commit aab964c

Browse files
cf-yparkOxyjun
cf-ypark
and
Oxyjun
authored
Integrating with GraphQL API Explorer (cloudflare#22282)
* Integrating with GraphQL API Explorer * updated CONTRIBUTING.md * Apply suggestions from code review Co-authored-by: Jun Lee <[email protected]> --------- Co-authored-by: Jun Lee <[email protected]>
1 parent caca61d commit aab964c

File tree

27 files changed

+2440
-2134
lines changed

27 files changed

+2440
-2134
lines changed

‎CONTRIBUTING.md‎

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -99,3 +99,71 @@ export default {
9999
would render as
100100

101101
<img width="870" alt="Screenshot 2024-02-20 at 14 29 22" src="https://github.com/cloudflare/cloudflare-docs/assets/28503158/56aa8016-b3b6-4d64-8213-b1a26f16534a">
102+
103+
## GraphQL API Explorer
104+
105+
If you are adding a code snippet to the documentation that is an executable GraphQL query, you can add `graphql-api-explorer` right after `graphql` in the code block metadata (both must be present). This will render a button that allows users to open the query in the [GraphQL API Explorer](https://graphql.cloudflare.com/explorer). For example:
106+
107+
````
108+
```graphql graphql-api-explorer title="A GraphQL query"
109+
query GraphqlExample($zoneTag: string, $start: Time, $end: Time) {
110+
viewer {
111+
zones(filter: { zoneTag: $zoneTag }) {
112+
firewallEventsAdaptive(
113+
filter: { datetime_gt: $start, datetime_lt: $end }
114+
limit: 2
115+
orderBy: [datetime_DESC]
116+
) {
117+
action
118+
datetime
119+
host: clientRequestHTTPHost
120+
}
121+
}
122+
}
123+
}
124+
```
125+
````
126+
127+
When a user selects the `Run in GraphQL API Explorer` button, the following variables will be pre-populated in the GraphQL API Explorer along with the query.
128+
129+
:::note
130+
The user must be logged in or have an API token saved to see the query and variables pre-populated.
131+
:::
132+
133+
```
134+
{"zoneTag":"ZONE_ID", "start":"2025-05-07T14:54:36Z", "end":"2025-05-07T20:54:36Z"}
135+
```
136+
137+
### Conventions to auto populate `Variables` section in the GraphQL API Explorer
138+
139+
By default, the `Variables` section will be automatically populated based on the variables used in the GraphQL query.
140+
141+
- Any variable name that includes `start` and has a type of `Time` --> start: "2025-05-09T14:58:06Z" (6 hours from the current time)
142+
- e.g. `datetimeStart` also has `start` keyword, so it will be recognized for a start time (or date)
143+
- Any variable name that includes `end` and has a type of `Time` --> end: "2025-05-09T20:58:06Z" (current time)
144+
- Any variable name that includes `start` and has a type of `Date` --> start: "2025-05-07" (24 hours from the current date)
145+
- Any variable name that includes `end` and has a type of `Date` --> end: "2025-05-08" (current date)
146+
- `zoneTag` and has a type of `string` --> zoneTag: "ZONE_ID"
147+
- `accountTag` and has a type of `string` --> accountTag: "ACCOUNT_ID"
148+
- Any variable name that includes `id` and has a type of `string` --> id: "REPLACE_WITH_ID"
149+
- Any variable name and has a type of string --> anyString: "REPLACE_WITH_STRING"
150+
- `limit` with type `*int*` --> limit: 100
151+
152+
In addition to the variables that are automatically populated, you can add custom variables by setting their values as a JSON string in the `graphql-api-explorer` metadata.
153+
154+
````
155+
```graphql graphql-api-explorer='{"uID": "something"}' title="A GraphQL query"
156+
query GraphqlExample($zoneTag: string, $start: Time, $end: Time) {
157+
viewer {
158+
zones(filter: { zoneTag: $zoneTag }) {
159+
...
160+
}
161+
}
162+
}
163+
````
164+
165+
The variables added via the metadata value will be merged with the automatically populated variables.
166+
167+
```
168+
{"zoneTag":"ZONE_ID", "start":"2025-05-07T14:54:36Z", "end":"2025-05-07T20:54:36Z", "uId": "something"}
169+
```

‎ec.config.mjs‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,7 @@ import lightTheme from "solarflare-theme/themes/cloudflare-light-color-theme.jso
77
import pluginWorkersPlayground from "./src/plugins/expressive-code/workers-playground.js";
88
import pluginOutputFrame from "./src/plugins/expressive-code/output-frame.js";
99
import pluginDefaultTitles from "./src/plugins/expressive-code/default-titles.js";
10+
import pluginGraphqlApiExplorer from "./src/plugins/expressive-code/graphql-api-explorer.js";
1011

1112
import { pluginCollapsibleSections } from "@expressive-code/plugin-collapsible-sections";
1213

@@ -16,6 +17,7 @@ export default defineEcConfig({
1617
pluginOutputFrame(),
1718
pluginDefaultTitles(),
1819
pluginCollapsibleSections(),
20+
pluginGraphqlApiExplorer(),
1921
],
2022
themes: [darkTheme, lightTheme],
2123
styleOverrides: {

‎src/content/docs/analytics/graphql-api/features/discovery/introspection.mdx‎

Lines changed: 90 additions & 87 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,6 @@ pcx_content_type: reference
33
title: Introspection
44
sidebar:
55
order: 41
6-
76
---
87

98
Cloudflare GraphQL API has a dynamic schema and exposes more than 70 datasets
@@ -50,104 +49,108 @@ etc).
5049
Alternatively, you can also do it manually by using `__schema` node with the
5150
needed directives.
5251

53-
```graphql title="A typical introspection query"
52+
```graphql graphql-api-explorer title="A typical introspection query"
5453
{
55-
__schema {
56-
queryType { name }
57-
mutationType { name }
58-
subscriptionType { name }
59-
types {
60-
...FullType
61-
}
62-
directives {
63-
name
64-
description
65-
locations
66-
args {
67-
...InputValue
68-
}
69-
}
70-
}
54+
__schema {
55+
queryType {
56+
name
57+
}
58+
mutationType {
59+
name
60+
}
61+
subscriptionType {
62+
name
63+
}
64+
types {
65+
...FullType
66+
}
67+
directives {
68+
name
69+
description
70+
locations
71+
args {
72+
...InputValue
73+
}
74+
}
75+
}
7176
}
7277
fragment TypeRef on __Type {
73-
kind
74-
name
75-
ofType {
76-
kind
77-
name
78-
ofType {
79-
kind
80-
name
81-
ofType {
82-
kind
83-
name
84-
ofType {
85-
kind
86-
name
87-
ofType {
88-
kind
89-
name
90-
ofType {
91-
kind
92-
name
93-
ofType {
94-
kind
95-
name
96-
}
97-
}
98-
}
99-
}
100-
}
101-
}
102-
}
78+
kind
79+
name
80+
ofType {
81+
kind
82+
name
83+
ofType {
84+
kind
85+
name
86+
ofType {
87+
kind
88+
name
89+
ofType {
90+
kind
91+
name
92+
ofType {
93+
kind
94+
name
95+
ofType {
96+
kind
97+
name
98+
ofType {
99+
kind
100+
name
101+
}
102+
}
103+
}
104+
}
105+
}
106+
}
107+
}
103108
}
104109
fragment InputValue on __InputValue {
105-
name
106-
description
107-
type { ...TypeRef }
108-
defaultValue
110+
name
111+
description
112+
type {
113+
...TypeRef
114+
}
115+
defaultValue
109116
}
110117
fragment FullType on __Type {
111-
kind
112-
name
113-
description
114-
fields(includeDeprecated: true) {
115-
name
116-
description
117-
args {
118-
...InputValue
119-
}
120-
type {
121-
...TypeRef
122-
}
123-
isDeprecated
124-
deprecationReason
125-
}
126-
inputFields {
127-
...InputValue
128-
}
129-
interfaces {
130-
...TypeRef
131-
}
132-
enumValues(includeDeprecated: true) {
133-
name
134-
description
135-
isDeprecated
136-
deprecationReason
137-
}
138-
possibleTypes {
139-
...TypeRef
140-
}
118+
kind
119+
name
120+
description
121+
fields(includeDeprecated: true) {
122+
name
123+
description
124+
args {
125+
...InputValue
126+
}
127+
type {
128+
...TypeRef
129+
}
130+
isDeprecated
131+
deprecationReason
132+
}
133+
inputFields {
134+
...InputValue
135+
}
136+
interfaces {
137+
...TypeRef
138+
}
139+
enumValues(includeDeprecated: true) {
140+
name
141+
description
142+
isDeprecated
143+
deprecationReason
144+
}
145+
possibleTypes {
146+
...TypeRef
147+
}
141148
}
142149
```
143150

144-
For more details on how to send a GraphQL request with curl, please refer to
145-
[this guide][4].
151+
For more details on how to send a GraphQL request with curl, please refer to [Execute a GraphQL query with curl][4].
146152

147153
[1]: https://graphql.org/learn/introspection/
148-
149154
[2]: /analytics/graphql-api/features/discovery/settings/
150-
151155
[3]: /analytics/graphql-api/getting-started/explore-graphql-schema/
152-
153156
[4]: /analytics/graphql-api/getting-started/execute-graphql-query/

0 commit comments

Comments
 (0)