chore(openapi): fix up duplicate VersionData types (#2182)

zchsh · web-flow · commit 6fe67e6feab0 · 2023-09-26T21:25:06.000-04:00
* chore: rename to sourceFile in ApiDocsVersionData

* chore: rm duplicate OpenApiDocsVersionData

* fix: old type import

* fix: finish sourceFile rename
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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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'
  * - ['<versionId>', '<serviceId>'] - 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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<OpenApiDocsPageConfig, 'githubSourceDirectory'> & {
 	context: GetStaticPropsContext<OpenApiDocsParams>
-	versionData: OpenApiDocsVersionData[]
+	versionData: ApiDocsVersionData[]
 }): Promise<GetStaticPropsResult<OpenApiDocsViewProps>> {
 	// 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
@@ -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
@@ -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
@@ -3,16 +3,16 @@
  * SPDX-License-Identifier: MPL-2.0
  */
 
-import { OpenApiDocsVersionData } from '../types'
+import type { ApiDocsVersionData } from 'lib/api-docs/types'
 
 /**
  * Sort version data in descending order.
  *
  * 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

Original file line number	Diff line number	Diff line change
`@@ -14,5 +14,5 @@ export interface ApiDocsVersionData {`
`14`	`14`	`// The release stage of this version of the API docs`
`15`	`15`	`releaseStage?: string // typically 'stable' \| 'preview'`
`16`	`16`	`// The schema file we'll load and render into the page for this version`
`17`		`- targetFile: GithubFile \| string`
	`17`	`+ sourceFile: GithubFile \| string`
`18`	`18`	`}`