From 179118c9ce2990a2d929d2231b8cd90b54395825 Mon Sep 17 00:00:00 2001 From: Zach Shilton <4624598+zchsh@users.noreply.github.com> Date: Tue, 18 Jul 2023 14:01:44 -0400 Subject: [PATCH] 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 | 3 +- config/development.json | 3 ++ config/preview.json | 3 ++ config/production.json | 3 ++ .../api-docs/vault-secrets/[[...page]].tsx | 51 +++++++++++++++++-- src/views/open-api-docs-view/index.tsx | 17 +++++++ src/views/open-api-docs-view/server.ts | 40 +++++++++++++++ src/views/open-api-docs-view/types.ts | 26 ++++++++++ 8 files changed, 142 insertions(+), 4 deletions(-) create mode 100644 src/views/open-api-docs-view/index.tsx create mode 100644 src/views/open-api-docs-view/server.ts create mode 100644 src/views/open-api-docs-view/types.ts diff --git a/config/base.json b/config/base.json index f03294fbf3..0e1933097c 100644 --- a/config/base.json +++ b/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 } } diff --git a/config/development.json b/config/development.json index 35a96d71bc..9a3d629221 100644 --- a/config/development.json +++ b/config/development.json @@ -11,5 +11,8 @@ }, "learn": { "max_static_paths": 1 + }, + "flags": { + "enable_hcp_vault_secrets_api_docs_revision": false } } diff --git a/config/preview.json b/config/preview.json index cdf98434f1..8c036b58ee 100644 --- a/config/preview.json +++ b/config/preview.json @@ -2,5 +2,8 @@ "extends": "base", "io_sites": { "max_static_paths": 10 + }, + "flags": { + "enable_hcp_vault_secrets_api_docs_revision": false } } diff --git a/config/production.json b/config/production.json index 271e9bdb3a..8303321c18 100644 --- a/config/production.json +++ b/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 } } diff --git a/src/pages/hcp/api-docs/vault-secrets/[[...page]].tsx b/src/pages/hcp/api-docs/vault-secrets/[[...page]].tsx index 5a5c3632eb..9f04937915 100644 --- a/src/pages/hcp/api-docs/vault-secrets/[[...page]].tsx +++ b/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 `` 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 + } + + /** + * Otherwise, use the existing API docs view + */ return ( = async () => { +export const getStaticPaths: GetStaticPaths = 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 = 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. diff --git a/src/views/open-api-docs-view/index.tsx b/src/views/open-api-docs-view/index.tsx new file mode 100644 index 0000000000..0eb9417c4a --- /dev/null +++ b/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 ( +
+

OpenApiDocsView Placeholder

+ 
+				{JSON.stringify(props, null, 2)}
+
+
+ ) +} + +export default OpenApiDocsView diff --git a/src/views/open-api-docs-view/server.ts b/src/views/open-api-docs-view/server.ts new file mode 100644 index 0000000000..aeed6f148d --- /dev/null +++ b/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 = 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, + }, + } +} diff --git a/src/views/open-api-docs-view/types.ts b/src/views/open-api-docs-view/types.ts new file mode 100644 index 0000000000..0c50a9eb66 --- /dev/null +++ b/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 +}