[Docs Site] Add query prop to APIRequest and CURL (#21609)

* [Docs Site] Add query prop to APIRequest and CURL

* validate apirequest query params via validate

* fix lint

* support array value in query

* bad format

* Update src/content/docs/style-guide/components/curl.mdx

Author: KianNH

src/components/APIRequest.astro

@@ -67,11 +67,19 @@ if (extraneousParameters.length > 0) {
 }
 
 for (const parameter of endpointParameters) {
-	if (parameter.in === "path") {
-		const encoded = encodeURIComponent(`{${parameter.name}}`);
-
-		if (parameters?.[parameter.name]) {
-			url.pathname = url.pathname.replace(encoded, parameters[parameter.name]);
+	const value = parameters?.[parameter.name];
+	if (value) {
+		if (parameter.in === "path") {
+			const encoded = encodeURIComponent(`{${parameter.name}}`);
+			url.pathname = url.pathname.replace(encoded, value);
+		} else if (parameter.in === "query") {
+			if (Array.isArray(value)) {
+				for (const v of value) {
+					url.searchParams.append(parameter.name, v);
+				}
+			} else {
+				url.searchParams.set(parameter.name, value);
+			}
 		}
 	}
 }

src/components/CURL.astro

@@ -15,18 +15,42 @@ const props = z.object({
 	headers: z.record(z.string(), z.string()).default({}),
 	json: z.union([Record, z.array(Record)]).optional(),
 	form: Record.optional(),
+	query: z
+		.record(z.string(), z.union([z.string(), z.array(z.string())]))
+		.optional(),
 	code: z
 		.custom<Omit<ComponentProps<typeof Code>, "code" | "lang">>()
 		.optional(),
 });
 
-const { method, url, headers, json, form, code } = props.parse(Astro.props);
+const {
+	method,
+	url: baseUrl,
+	headers,
+	json,
+	form,
+	query,
+	code,
+} = props.parse(Astro.props);
 
 if (json && form) {
 	throw new Error("[CURL] Cannot use both 'json' and 'form' properties.");
 }
 
-const lines = [`curl ${url}`, `\t--request ${method}`];
+const url = new URL(baseUrl);
+if (query) {
+	for (const [key, value] of Object.entries(query)) {
+		if (Array.isArray(value)) {
+			for (const v of value) {
+				url.searchParams.append(key, v);
+			}
+		} else {
+			url.searchParams.set(key, value);
+		}
+	}
+}
+
+const lines = [`curl "${url.toString()}"`, `\t--request ${method}`];
 
 if (headers) {
 	for (const [key, value] of Object.entries(headers)) {

src/content/docs/style-guide/components/api-request.mdx

@@ -19,7 +19,7 @@ import { APIRequest } from "~/components";
 	path="/zones/{zone_id}/api_gateway/settings/schema_validation"
 	method="PUT"
 	json={{
-		validation_default_mitigation_action: "block"
+		validation_default_mitigation_action: "block",
 	}}
 />
 
@@ -36,7 +36,7 @@ import { APIRequest } from "~/components";
 	method="POST"
 	form={{
 		requireSignedURLs: true,
-		metadata: '{"key":"value"}'
+		metadata: '{"key":"value"}',
 	}}
 />
 
@@ -54,6 +54,14 @@ import { APIRequest } from "~/components";
 		},
 	]}
 />
+
+<APIRequest
+	path="/zones/{zone_id}/page_shield/scripts"
+	method="GET"
+	parameters={{
+		direction: "asc",
+	}}
+/>
 ```
 
 ## `<APIRequest>` Props
@@ -80,7 +88,16 @@ The HTTP method to use.
 
 **type:** `Record<string, any>`
 
-The path parameters to substitute.
+The parameters to substitute - either in the URL path or as query parameters.
+
+For example, `/zones/{zone_id}/page_shield/scripts` can be transformed into `/zones/123/page_shield/scripts?direction=asc` with the following:
+
+```mdx
+parameters={{
+	zone_id: "123",
+	direction: "asc"
+}}
+```
 
 If not provided, the component will default to an environment variable. For example, `{setting_id}` will be replaced with `$SETTING_ID`.
 
@@ -98,4 +115,4 @@ If required properties are missing, the component will throw an error.
 
 The FormData payload to send.
 
-This field is not currently validated against the schema.
+This field is not currently validated against the schema.

src/content/docs/style-guide/components/curl.mdx

@@ -23,8 +23,12 @@ import { CURL } from "~/components";
 	json={{
 		key: "va'l'ue",
 	}}
+	query={{
+		foo: "bar",
+		bar: ["baz", "qux"],
+	}}
 	code={{
-		mark: "value"
+		mark: "value",
 	}}
 />
 
@@ -35,7 +39,7 @@ import { CURL } from "~/components";
 		key: "value",
 	}}
 	code={{
-		mark: "value"
+		mark: "value",
 	}}
 />
 ```
@@ -76,6 +80,12 @@ JSON data to include in the request.
 
 The FormData payload to send.
 
+### `query`
+
+**type:** `Record<string, string | string[]>`
+
+URL query parameters to append to the request URL.
+
 ### `code`
 
 **type:** `object`
@@ -84,4 +94,4 @@ An object of Expressive Code props, the following props are available:
 
 - [Base Props](https://expressive-code.com/key-features/code-component/#available-props)
 - [Line Marker Props](https://expressive-code.com/key-features/text-markers/#props)
-- [Collapsible Sections Props](https://expressive-code.com/plugins/collapsible-sections/#props)
+- [Collapsible Sections Props](https://expressive-code.com/plugins/collapsible-sections/#props)