chore: add flag for revised Vault Secrets API docs (#2082)

* chore: set up flag

* feat: add placeholder for open-api-docs-view

* feat: use the flag for vault-secrets API docs

* chore: revert flags

config/base.json

@@ -45,6 +45,7 @@
 	"flags": {
 		"enable_datadog": true,
 		"enable_io_beta_cta": true,
-		"enable_unified_search": true
+		"enable_unified_search": true,
+		"enable_hcp_vault_secrets_api_docs_revision": false
 	}
 }

config/development.json

@@ -11,5 +11,8 @@
 	},
 	"learn": {
 		"max_static_paths": 1
+	},
+	"flags": {
+		"enable_hcp_vault_secrets_api_docs_revision": false
 	}
 }

config/preview.json

@@ -2,5 +2,8 @@
 	"extends": "base",
 	"io_sites": {
 		"max_static_paths": 10
+	},
+	"flags": {
+		"enable_hcp_vault_secrets_api_docs_revision": false
 	}
 }

config/production.json

@@ -14,5 +14,8 @@
 			"idp_url": "https://auth.idp.hashicorp.com"
 		},
 		"product_slugs_with_integrations": ["vault", "waypoint", "nomad"]
+	},
+	"flags": {
+		"enable_hcp_vault_secrets_api_docs_revision": false
 	}
 }

src/pages/hcp/api-docs/vault-secrets/[[...page]].tsx

@@ -12,6 +12,12 @@ import {
 } from 'views/api-docs-view/server'
 import { buildApiDocsBreadcrumbs } from 'views/api-docs-view/server/get-api-docs-static-props/utils'
 import { fetchCloudApiVersionData } from 'views/api-docs-view/utils'
+// Revised view
+import OpenApiDocsView from 'views/open-api-docs-view'
+import {
+	getStaticPaths as getOpenApiDocsStaticPaths,
+	getStaticProps as getOpenApiDocsStaticProps,
+} from 'views/open-api-docs-view/server'
 // Components
 import {
 	PathTruncationAside,
@@ -21,8 +27,15 @@ import {
 import type { OperationObjectType } from 'components/open-api-page/types'
 import type { ApiDocsViewProps } from 'views/api-docs-view/types'
 import type { GetStaticPaths, GetStaticProps } from 'next'
+import type { OpenApiDocsViewProps } from 'views/open-api-docs-view/types'
 import { isDeployPreview } from 'lib/env-checks'
 
+/**
+ * 🚩 Flag to use the work-in-progress revised API docs view & server functions.
+ */
+const USE_REVISED_TEMPLATE =
+	__config.flags.enable_hcp_vault_secrets_api_docs_revision
+
 /**
  * The product slug is used to fetch product data for the layout.
  */
@@ -49,7 +62,19 @@ const GITHUB_SOURCE_DIRECTORY = {
  * Render `<ApiDocsView />` with custom operation path truncation
  * for HCP Vault secrets.
  */
-function HcpVaultSecretsApiDocsView(props: ApiDocsViewProps) {
+function HcpVaultSecretsApiDocsView(
+	props: ApiDocsViewProps | OpenApiDocsViewProps
+) {
+	/**
+	 * 🚩 If the flag is enabled, use the revised template
+	 */
+	if ('IS_REVISED_TEMPLATE' in props) {
+		return <OpenApiDocsView {...props} />
+	}
+
+	/**
+	 * Otherwise, use the existing API docs view
+	 */
 	return (
 		<ApiDocsView
 			{...props}
@@ -64,7 +89,17 @@ function HcpVaultSecretsApiDocsView(props: ApiDocsViewProps) {
 /**
  * Get static paths, using `versionData` fetched from GitHub.
  */
-export const getStaticPaths: GetStaticPaths<ApiDocsParams> = async () => {
+export const getStaticPaths: GetStaticPaths<ApiDocsParams> = async (ctx) => {
+	/**
+	 * 🚩 If the flag is enabled, use the revised template
+	 */
+	if (USE_REVISED_TEMPLATE) {
+		return await getOpenApiDocsStaticPaths(ctx)
+	}
+
+	/**
+	 * Otherwise, use the existing API docs view
+	 */
 	// If we are in a deploy preview, don't pre-render any paths
 	if (isDeployPreview()) {
 		return { paths: [], fallback: 'blocking' }
@@ -81,9 +116,19 @@ export const getStaticPaths: GetStaticPaths<ApiDocsParams> = async () => {
  * and of course we need specific data for the current version.
  */
 export const getStaticProps: GetStaticProps<
-	ApiDocsViewProps,
+	ApiDocsViewProps | OpenApiDocsViewProps,
 	ApiDocsParams
 > = async ({ params }: { params: ApiDocsParams }) => {
+	/**
+	 * 🚩 If the flag is enabled, use the revised template
+	 */
+	if (USE_REVISED_TEMPLATE) {
+		return await getOpenApiDocsStaticProps({ params })
+	}
+
+	/**
+	 * Otherwise, use the existing API docs view
+	 */
 	// Fetch all version data, based on remote `stable` & `preview` subfolders
 	const versionData = await fetchCloudApiVersionData(GITHUB_SOURCE_DIRECTORY)
 	// If we can't find any version data at all, render a 404 page.

src/views/open-api-docs-view/index.tsx

@@ -0,0 +1,17 @@
+import type { OpenApiDocsViewProps } from './types'
+
+/**
+ * Placeholder for a revised OpenAPI docs view.
+ */
+function OpenApiDocsView(props: OpenApiDocsViewProps) {
+	return (
+		<div style={{ border: '1px solid magenta' }}>
+			<h1>OpenApiDocsView Placeholder</h1>
+			<pre>
+				<code>{JSON.stringify(props, null, 2)}</code>
+			</pre>
+		</div>
+	)
+}
+
+export default OpenApiDocsView

src/views/open-api-docs-view/server.ts

@@ -0,0 +1,40 @@
+import { GetStaticPaths, GetStaticProps } from 'next'
+import { OpenApiDocsParams, OpenApiDocsViewProps } from './types'
+
+/**
+ * Get static paths for the view.
+ *
+ * Initially, without versioning, we expect a single page. We use
+ * `getStaticPaths` for flag-based compatibility with the previous template.
+ *
+ * Later, when we implement versioned API docs for the new template,
+ * we'll likely need to retain `getStaticPaths`, using separate paths
+ * for each version of the OpenAPI documents that we detect.
+ */
+export const getStaticPaths: GetStaticPaths<OpenApiDocsParams> = async () => {
+	// For the new template, regardless of whether we're in a deploy preview
+	// or production, statically render the single view.
+	return {
+		paths: [{ params: { page: [] } }],
+		fallback: false,
+	}
+}
+
+/**
+ * Get static props for the view.
+ *
+ * This is where we expect to fetch the OpenAPI document, and transform
+ * the schema `.json` data into props for the view component.
+ *
+ * For now, we have a placeholder. We'll expand this as we build out the view.
+ */
+export const getStaticProps: GetStaticProps<
+	OpenApiDocsViewProps
+> = async () => {
+	return {
+		props: {
+			placeholder: 'placeholder data for the revised API docs template',
+			IS_REVISED_TEMPLATE: true,
+		},
+	}
+}

src/views/open-api-docs-view/types.ts

@@ -0,0 +1,26 @@
+import type { ParsedUrlQuery } from 'querystring'
+
+/**
+ * Params type for `getStaticPaths` and `getStaticProps`.
+ * Encodes our assumption that a `[[page]].tsx` file is being used.
+ *
+ * Note: this is only needed for compatibility with the previous API docs,
+ * which could potentially render multiple pages, one for each service.
+ * In this revised template, we only render a single page.
+ *
+ * We will still need a dynamic route for versioning, but will need a refactor.
+ * TODO: revise this type once we've fully activated and then removed the
+ * `enable_hcp_vault_secrets_api_docs_revision` flag.
+ */
+export interface OpenApiDocsParams extends ParsedUrlQuery {
+	page: string[]
+}
+
+/**
+ * We'll use this type to document the shape of props for the view component.
+ * For now, we have a placeholder. We'll expand this as we build out the view.
+ */
+export interface OpenApiDocsViewProps {
+	placeholder: string
+	IS_REVISED_TEMPLATE: true
+}