From 6fe67e6feab042b3faac8bc4dc79ba523f084e68 Mon Sep 17 00:00:00 2001 From: Zach Shilton <4624598+zchsh@users.noreply.github.com> Date: Tue, 26 Sep 2023 21:25:06 -0400 Subject: [PATCH] chore(openapi): fix up duplicate VersionData types (#2182) * chore: rename to sourceFile in ApiDocsVersionData * chore: rm duplicate OpenApiDocsVersionData * fix: old type import * fix: finish sourceFile rename --- .../fetch-cloud-api-version-data/index.ts | 4 ++-- src/lib/api-docs/types.ts | 2 +- src/pages/boundary/api-docs/[[...page]].tsx | 10 ++++------ .../hcp/api-docs/vault-secrets/[[...page]].tsx | 16 ++++------------ src/pages/waypoint/api-docs/[[...page]].tsx | 10 ++++------ .../components/api-docs-version-alert/types.ts | 2 +- .../fetch-api-docs-paths.ts | 16 ++++++++-------- .../server/get-api-docs-static-paths/index.ts | 5 +++-- .../server/get-api-docs-static-props/index.ts | 9 +++------ .../utils/build-schema-props.ts | 14 +++++++------- .../utils/build-version-switcher-data.ts | 2 +- src/views/api-docs-view/types.ts | 12 ------------ src/views/open-api-docs-view/server.ts | 6 +++--- src/views/open-api-docs-view/types.ts | 12 ------------ .../utils/find-default-version.ts | 6 +++--- .../utils/sort-date-version-data.ts | 6 +++--- 16 files changed, 47 insertions(+), 85 deletions(-) diff --git a/src/lib/api-docs/fetch-cloud-api-version-data/index.ts b/src/lib/api-docs/fetch-cloud-api-version-data/index.ts index 55de9a5dbb..22fc03bff2 100644 --- a/src/lib/api-docs/fetch-cloud-api-version-data/index.ts +++ b/src/lib/api-docs/fetch-cloud-api-version-data/index.ts @@ -53,13 +53,13 @@ async function fetchCloudApiVersionData( // Construct the version metadata needed to fetch static props const versionId = versionIdFromPath(filePathFromRepoRoot) const releaseStage = releaseStageFromPath(filePathFromRepoRoot) - const targetFile = { + const sourceFile = { owner: githubDir.owner, repo: githubDir.repo, path: filePathFromRepoRoot, ref: githubDir.ref, } - return { versionId, releaseStage, targetFile } + return { versionId, releaseStage, sourceFile } }) // Return the version data, sorted in descending order return sortDateVersionData(versionData) diff --git a/src/lib/api-docs/types.ts b/src/lib/api-docs/types.ts index d5dbde4304..ddd47fa874 100644 --- a/src/lib/api-docs/types.ts +++ b/src/lib/api-docs/types.ts @@ -14,5 +14,5 @@ export interface ApiDocsVersionData { // The release stage of this version of the API docs releaseStage?: string // typically 'stable' | 'preview' // The schema file we'll load and render into the page for this version - targetFile: GithubFile | string + sourceFile: GithubFile | string } diff --git a/src/pages/boundary/api-docs/[[...page]].tsx b/src/pages/boundary/api-docs/[[...page]].tsx index be8c17162f..b59d923045 100644 --- a/src/pages/boundary/api-docs/[[...page]].tsx +++ b/src/pages/boundary/api-docs/[[...page]].tsx @@ -13,10 +13,8 @@ import { ApiDocsParams, } from 'views/api-docs-view/server' // Types -import type { - ApiDocsVersionData, - ApiDocsViewProps, -} from 'views/api-docs-view/types' +import type { ApiDocsVersionData } from 'lib/api-docs/types' +import type { ApiDocsViewProps } from 'views/api-docs-view/types' import type { GetStaticPaths, GetStaticProps } from 'next' /** @@ -41,7 +39,7 @@ const TARGET_LOCAL_FILE = '../../internal/gen/controller.swagger.json' * version data from elsewhere, as we do for `/hcp/api-docs/packer`. */ function getVersionData(): ApiDocsVersionData[] { - const targetFile = isDeployPreview(PRODUCT_SLUG) + const sourceFile = isDeployPreview(PRODUCT_SLUG) ? TARGET_LOCAL_FILE : { owner: 'hashicorp', @@ -59,7 +57,7 @@ function getVersionData(): ApiDocsVersionData[] { * That might better align with versioned API docs for Boundary. */ versionId: 'latest', - targetFile, + sourceFile, }, ] } diff --git a/src/pages/hcp/api-docs/vault-secrets/[[...page]].tsx b/src/pages/hcp/api-docs/vault-secrets/[[...page]].tsx index 8319da2602..da4d323be2 100644 --- a/src/pages/hcp/api-docs/vault-secrets/[[...page]].tsx +++ b/src/pages/hcp/api-docs/vault-secrets/[[...page]].tsx @@ -98,19 +98,11 @@ export const getStaticProps: GetStaticProps< } return await getOpenApiDocsStaticProps({ - basePath: PAGE_CONFIG.basePath, - productSlug: PAGE_CONFIG.productSlug, - serviceProductSlug: PAGE_CONFIG.serviceProductSlug, - statusIndicatorConfig: PAGE_CONFIG.statusIndicatorConfig, - navResourceItems: PAGE_CONFIG.navResourceItems, - groupOperationsByPath: PAGE_CONFIG.groupOperationsByPath, - massageSchemaForClient: PAGE_CONFIG.massageSchemaForClient, - // Pass params to getStaticProps, this is used for versioning + // Pass page configuration + ...PAGE_CONFIG, + // Pass context and versionData to getStaticProps, needed for versioning context: { params }, - // Handle rename of `targetFile` to `sourceFile` for new template - versionData: versionData.map(({ targetFile, ...rest }) => { - return { ...rest, sourceFile: targetFile } - }), + versionData, }) } diff --git a/src/pages/waypoint/api-docs/[[...page]].tsx b/src/pages/waypoint/api-docs/[[...page]].tsx index ffebf30f95..8134683d06 100644 --- a/src/pages/waypoint/api-docs/[[...page]].tsx +++ b/src/pages/waypoint/api-docs/[[...page]].tsx @@ -13,10 +13,8 @@ import { ApiDocsParams, } from 'views/api-docs-view/server' // Components -import type { - ApiDocsVersionData, - ApiDocsViewProps, -} from 'views/api-docs-view/types' +import type { ApiDocsVersionData } from 'lib/api-docs/types' +import type { ApiDocsViewProps } from 'views/api-docs-view/types' import type { GetStaticPaths, GetStaticProps } from 'next' import { buildApiDocsBreadcrumbs } from 'views/api-docs-view/server/get-api-docs-static-props/utils' import { @@ -57,7 +55,7 @@ const MAY_HAVE_CIRCULAR_REFERENCES = true * version data from elsewhere, as we do for `/hcp/api-docs/packer`. */ function getVersionData(): ApiDocsVersionData[] { - const targetFile = isDeployPreview(PRODUCT_SLUG) + const sourceFile = isDeployPreview(PRODUCT_SLUG) ? TARGET_LOCAL_FILE : { owner: 'hashicorp', @@ -75,7 +73,7 @@ function getVersionData(): ApiDocsVersionData[] { * That might better align with versioned API docs for Waypoint. */ versionId: 'latest', - targetFile, + sourceFile, }, ] } diff --git a/src/views/api-docs-view/components/api-docs-version-alert/types.ts b/src/views/api-docs-view/components/api-docs-version-alert/types.ts index a11be535ee..c06f5ade67 100644 --- a/src/views/api-docs-view/components/api-docs-version-alert/types.ts +++ b/src/views/api-docs-view/components/api-docs-version-alert/types.ts @@ -3,7 +3,7 @@ * SPDX-License-Identifier: MPL-2.0 */ -import type { ApiDocsVersionData } from 'views/api-docs-view/types' +import type { ApiDocsVersionData } from 'lib/api-docs/types' export interface ApiDocsVersionAlertProps { isVersionedUrl: boolean diff --git a/src/views/api-docs-view/server/get-api-docs-static-paths/fetch-api-docs-paths.ts b/src/views/api-docs-view/server/get-api-docs-static-paths/fetch-api-docs-paths.ts index d749f8bda8..4bf5620ab5 100644 --- a/src/views/api-docs-view/server/get-api-docs-static-paths/fetch-api-docs-paths.ts +++ b/src/views/api-docs-view/server/get-api-docs-static-paths/fetch-api-docs-paths.ts @@ -17,10 +17,10 @@ import { import type { GithubFile } from 'lib/fetch-github-file' /** - * Given a `targetFile` pointing to a valid OpenAPI Swagger `.json` file, + * Given a `sourceFile` pointing to a valid OpenAPI Swagger `.json` file, * * Return an array of path parts representing partial URLs on which - * we'll want to render OpenAPI documentation for the `targetFile`. + * we'll want to render OpenAPI documentation for the `sourceFile`. * * Note: path parts will differ based on whether a `versionId` is provided, * and will differ if there is only a single "service". @@ -34,7 +34,7 @@ import type { GithubFile } from 'lib/fetch-github-file' * - ['', ''] - when there are multiple services */ async function fetchApiDocsPaths({ - targetFile, + sourceFile, versionId, mayHaveCircularReferences, }: { @@ -45,7 +45,7 @@ async function fetchApiDocsPaths({ * - Provide a `string` file path, relative to the current working directory * from which the website is run, to load a local file. */ - targetFile: GithubFile | string + sourceFile: GithubFile | string versionId?: string /** * The Waypoint API docs have circular references. @@ -61,17 +61,17 @@ async function fetchApiDocsPaths({ /** * Grab the schema. * - * If the provided `targetFile` is a string, we'll load from the filesystem. + * If the provided `sourceFile` is a string, we'll load from the filesystem. * Else, we assume a remote GitHub file, and load using the GitHub API. * * TODO: would be ideal to validate & properly type the schema, eg with `zod`. * For now, we cast it to the good-enough ApiDocsSwaggerSchema. */ let schema - if (typeof targetFile === 'string') { - schema = await processSchemaFile(targetFile) + if (typeof sourceFile === 'string') { + schema = await processSchemaFile(sourceFile) } else { - const swaggerFile = await fetchGithubFile(targetFile) + const swaggerFile = await fetchGithubFile(sourceFile) schema = await processSchemaString(swaggerFile) } diff --git a/src/views/api-docs-view/server/get-api-docs-static-paths/index.ts b/src/views/api-docs-view/server/get-api-docs-static-paths/index.ts index c169a2d5ad..1da48e107a 100644 --- a/src/views/api-docs-view/server/get-api-docs-static-paths/index.ts +++ b/src/views/api-docs-view/server/get-api-docs-static-paths/index.ts @@ -10,7 +10,8 @@ import { findLatestStableVersion } from 'lib/api-docs' import { fetchApiDocsPaths } from './fetch-api-docs-paths' // Types import type { GetStaticPathsResult } from 'next' -import type { ApiDocsVersionData, ApiDocsParams } from '../../types' +import type { ApiDocsVersionData } from 'lib/api-docs/types' +import type { ApiDocsParams } from '../../types' import type { ProductSlug } from 'types/products' /** @@ -71,7 +72,7 @@ export async function getApiDocsStaticPaths({ } // Parse the path parts for all API docs pages we need to statically render. const apiDocsPaths = await fetchApiDocsPaths({ - targetFile: latestStableVersion.targetFile, + sourceFile: latestStableVersion.sourceFile, mayHaveCircularReferences, }) diff --git a/src/views/api-docs-view/server/get-api-docs-static-props/index.ts b/src/views/api-docs-view/server/get-api-docs-static-props/index.ts index 05a8c7b60b..e26b87507d 100644 --- a/src/views/api-docs-view/server/get-api-docs-static-props/index.ts +++ b/src/views/api-docs-view/server/get-api-docs-static-props/index.ts @@ -16,11 +16,8 @@ import { } from './utils' // Types import type { GetStaticPropsResult } from 'next' -import type { - ApiDocsServiceData, - ApiDocsVersionData, - ApiDocsViewProps, -} from '../../types' +import type { ApiDocsVersionData } from 'lib/api-docs/types' +import type { ApiDocsServiceData, ApiDocsViewProps } from '../../types' import type { ProductData, ProductSlug } from 'types/products' import type { BreadcrumbLink } from 'components/breadcrumb-bar' import { cachedGetProductData } from 'lib/get-product-data' @@ -115,7 +112,7 @@ export async function getApiDocsStaticProps({ * using the current version's Swagger file. */ const schemaProps = await buildSchemaProps({ - targetFile: currentVersion.targetFile, + sourceFile: currentVersion.sourceFile, serviceId, mayHaveCircularReferences, }) diff --git a/src/views/api-docs-view/server/get-api-docs-static-props/utils/build-schema-props.ts b/src/views/api-docs-view/server/get-api-docs-static-props/utils/build-schema-props.ts index ec9da4d9c6..172f2c8d36 100644 --- a/src/views/api-docs-view/server/get-api-docs-static-props/utils/build-schema-props.ts +++ b/src/views/api-docs-view/server/get-api-docs-static-props/utils/build-schema-props.ts @@ -23,7 +23,7 @@ import type { OperationObjectType } from 'components/open-api-page/types' import type { ApiDocsSwaggerSchema, ApiDocsServiceData } from '../../../types' /** - * Given a targetFile, and optional target `serviceId`, + * Given a sourceFile, and optional target `serviceId`, * fetch the target swagger `.json` file, parse schema information, and * Return the `schema`, `serviceData` for the target `serviceId`, * `operationObjects`, and a list of all `serviceId`s. @@ -35,11 +35,11 @@ import type { ApiDocsSwaggerSchema, ApiDocsServiceData } from '../../../types' * returns `{ notFound: true }`, which signals that a 404 page should be shown. */ async function buildSchemaProps({ - targetFile, + sourceFile, serviceId, mayHaveCircularReferences, }: { - targetFile: GithubFile + sourceFile: GithubFile serviceId?: string /** * The Waypoint API docs have circular references. @@ -63,17 +63,17 @@ async function buildSchemaProps({ /** * Grab the schema. * - * If the provided `targetFile` is a string, we'll load from the filesystem. + * If the provided `sourceFile` is a string, we'll load from the filesystem. * Else, we assume a remote GitHub file, and load using the GitHub API. * * TODO: would be ideal to validate & properly type the schema, eg with `zod`. * For now, we cast it to the good-enough ApiDocsSwaggerSchema. */ let schema - if (typeof targetFile === 'string') { - schema = await processSchemaFile(targetFile) + if (typeof sourceFile === 'string') { + schema = await processSchemaFile(sourceFile) } else { - const swaggerFile = await fetchGithubFile(targetFile) + const swaggerFile = await fetchGithubFile(sourceFile) schema = await processSchemaString(swaggerFile) } diff --git a/src/views/api-docs-view/server/get-api-docs-static-props/utils/build-version-switcher-data.ts b/src/views/api-docs-view/server/get-api-docs-static-props/utils/build-version-switcher-data.ts index 1f85ace3cd..d25f29d33d 100644 --- a/src/views/api-docs-view/server/get-api-docs-static-props/utils/build-version-switcher-data.ts +++ b/src/views/api-docs-view/server/get-api-docs-static-props/utils/build-version-switcher-data.ts @@ -3,7 +3,7 @@ * SPDX-License-Identifier: MPL-2.0 */ -import { ApiDocsVersionData } from '../../../types' +import type { ApiDocsVersionData } from 'lib/api-docs/types' import { findLatestStableVersion } from 'lib/api-docs' /** diff --git a/src/views/api-docs-view/types.ts b/src/views/api-docs-view/types.ts index 6be5e77c74..7837b04ab9 100644 --- a/src/views/api-docs-view/types.ts +++ b/src/views/api-docs-view/types.ts @@ -44,18 +44,6 @@ export interface ApiDocsServiceData { operations: OperationObjectType[] } -/** - * A type to describe versioned API docs source files. - */ -export interface ApiDocsVersionData { - // A unique id for this version, used to construct URL paths for example - versionId: string - // The release stage of this version of the API docs - releaseStage?: string // typically 'stable' | 'preview' - // The schema file we'll load and render into the page for this version - targetFile: GithubFile | string -} - /** * Props needed to render `ApiDocsView`. */ diff --git a/src/views/open-api-docs-view/server.ts b/src/views/open-api-docs-view/server.ts index 69025e1307..d3746f6012 100644 --- a/src/views/open-api-docs-view/server.ts +++ b/src/views/open-api-docs-view/server.ts @@ -25,10 +25,10 @@ import type { GetStaticPropsResult, } from 'next' import type { OpenAPIV3 } from 'openapi-types' +import type { ApiDocsVersionData } from 'lib/api-docs/types' import type { OpenApiDocsParams, OpenApiDocsViewProps, - OpenApiDocsVersionData, OpenApiDocsPageConfig, } from './types' @@ -75,7 +75,7 @@ export async function getStaticProps({ navResourceItems = [], }: Omit & { context: GetStaticPropsContext - versionData: OpenApiDocsVersionData[] + versionData: ApiDocsVersionData[] }): Promise> { // Get the product data const productData = cachedGetProductData(productSlug) @@ -87,7 +87,7 @@ export async function getStaticProps({ const versionId = pathParts?.length > 1 ? pathParts[0] : null const isVersionedUrl = typeof versionId === 'string' // Resolve the current version - let targetVersion: OpenApiDocsVersionData | undefined + let targetVersion: ApiDocsVersionData | undefined if (isVersionedUrl) { targetVersion = versionData.find((v) => v.versionId === versionId) } else { diff --git a/src/views/open-api-docs-view/types.ts b/src/views/open-api-docs-view/types.ts index 6fc44c09e3..be122471cf 100644 --- a/src/views/open-api-docs-view/types.ts +++ b/src/views/open-api-docs-view/types.ts @@ -44,18 +44,6 @@ export interface OperationProps { */ export type OperationGroup = { heading: string; items: OperationProps[] } -/** - * A type to describe versioned API docs source files. - */ -export interface OpenApiDocsVersionData { - // A unique id for this version, used to construct URL paths for example - versionId: string - // The release stage of this version of the API docs - releaseStage?: string // typically 'stable' | 'preview' - // The schema file we'll load and render into the page for this version - sourceFile: GithubFile | string -} - /** * Params type for `getStaticPaths` and `getStaticProps`. * Encodes our assumption that a `[[...page]].tsx` file is being used. diff --git a/src/views/open-api-docs-view/utils/find-default-version.ts b/src/views/open-api-docs-view/utils/find-default-version.ts index add921babf..15918de755 100644 --- a/src/views/open-api-docs-view/utils/find-default-version.ts +++ b/src/views/open-api-docs-view/utils/find-default-version.ts @@ -3,7 +3,7 @@ * SPDX-License-Identifier: MPL-2.0 */ -import { OpenApiDocsVersionData } from '../types' +import { ApiDocsVersionData } from 'lib/api-docs/types' import { sortDateVersionData } from './sort-date-version-data' /** @@ -20,8 +20,8 @@ import { sortDateVersionData } from './sort-date-version-data' * We'd need to update the sort logic in order to support other formats. */ export function findDefaultVersion( - versionData: OpenApiDocsVersionData[] -): OpenApiDocsVersionData { + versionData: ApiDocsVersionData[] +): ApiDocsVersionData { // If we have exactly one version, we'll show that as the default. if (versionData.length === 1) { return versionData[0] diff --git a/src/views/open-api-docs-view/utils/sort-date-version-data.ts b/src/views/open-api-docs-view/utils/sort-date-version-data.ts index be2c31cbf1..ff30b63902 100644 --- a/src/views/open-api-docs-view/utils/sort-date-version-data.ts +++ b/src/views/open-api-docs-view/utils/sort-date-version-data.ts @@ -3,7 +3,7 @@ * SPDX-License-Identifier: MPL-2.0 */ -import { OpenApiDocsVersionData } from '../types' +import type { ApiDocsVersionData } from 'lib/api-docs/types' /** * Sort version data in descending order. @@ -11,8 +11,8 @@ import { OpenApiDocsVersionData } from '../types' * Note: only works with `YYYY-MM-DD` version formats. */ export function sortDateVersionData( - versionData: OpenApiDocsVersionData[] -): OpenApiDocsVersionData[] { + versionData: ApiDocsVersionData[] +): ApiDocsVersionData[] { return versionData.sort((a, b) => { // We expect consistent YYYY-MM-DD formatting, so string compare works fine const aBeforeB = a.versionId > b.versionId