From 3399ca30b302794821399dd974b6bc597c984c69 Mon Sep 17 00:00:00 2001 From: Zachary Shilton <4624598+zchsh@users.noreply.github.com> Date: Wed, 20 Oct 2021 11:29:54 -0400 Subject: [PATCH] website: use shared open-api-page component (#1519) * website: use canary release of open-api-page * website: bump to latest open-api-page pre-release * chore: bump to latest open-api-page pre-release * chore: refresh package files from main to avoid conflicts * bump to stable open-api-page release --- website/components/openapi-page/index.jsx | 94 ----------- .../components/openapi-page/index.props.js | 32 ---- .../partials/chevron-down/black.jsx | 23 --- .../collapsible/collapsible.module.css | 18 -- .../partials/collapsible/index.js | 81 --------- .../partials/operation-object/index.js | 154 ------------------ .../partials/operation-object/index.props.js | 61 ------- .../operation-object.module.css | 145 ----------------- .../partials/property-object/index.js | 91 ----------- .../property-object.module.css | 85 ---------- .../partials/response-object/index.js | 27 --- .../partials/response-object/index.props.js | 16 -- .../components/openapi-page/style.module.css | 57 ------- .../openapi-page/utils/routing-utils.js | 121 -------------- website/package-lock.json | 129 +++++++++++---- website/package.json | 1 + website/pages/api-docs/[[...page]].jsx | 16 +- 17 files changed, 108 insertions(+), 1043 deletions(-) delete mode 100644 website/components/openapi-page/index.jsx delete mode 100644 website/components/openapi-page/index.props.js delete mode 100644 website/components/openapi-page/partials/chevron-down/black.jsx delete mode 100644 website/components/openapi-page/partials/collapsible/collapsible.module.css delete mode 100644 website/components/openapi-page/partials/collapsible/index.js delete mode 100644 website/components/openapi-page/partials/operation-object/index.js delete mode 100644 website/components/openapi-page/partials/operation-object/index.props.js delete mode 100644 website/components/openapi-page/partials/operation-object/operation-object.module.css delete mode 100644 website/components/openapi-page/partials/property-object/index.js delete mode 100644 website/components/openapi-page/partials/property-object/property-object.module.css delete mode 100644 website/components/openapi-page/partials/response-object/index.js delete mode 100644 website/components/openapi-page/partials/response-object/index.props.js delete mode 100644 website/components/openapi-page/style.module.css delete mode 100644 website/components/openapi-page/utils/routing-utils.js diff --git a/website/components/openapi-page/index.jsx b/website/components/openapi-page/index.jsx deleted file mode 100644 index a3853708b..000000000 --- a/website/components/openapi-page/index.jsx +++ /dev/null @@ -1,94 +0,0 @@ -import { useState, useRef } from 'react' -import Link from 'next/link' -import OperationObject from './partials/operation-object' -import HashiHead from '@hashicorp/react-head' -import DocsSidenav from '@hashicorp/react-docs-sidenav' -import Content from '@hashicorp/react-content' -import { getPathsFromSchema, getPropsForPage } from './utils/routing-utils' -import styles from './style.module.css' -import useOnClickOutside from 'lib/hooks/use-on-click-outside' - -function OpenApiPage({ - info, - operationCategory, - navData, - productName, - productSlug, - currentPath, -}) { - const operationsRef = useRef(null) - const [expandedOperations, setExpandedOperations] = useState([]) - useOnClickOutside(operationsRef, () => setExpandedOperations([])) - - function setOperationState(slug, isExpanded) { - const newStates = expandedOperations.filter((s) => s !== slug) - if (isExpanded) newStates.push(slug) - setExpandedOperations(newStates) - } - - const pageTitle = operationCategory ? operationCategory.name : info.title - - return ( -
- - - -

- {info.title} -

-

- {operationCategory.name} -

-
- {operationCategory.operations.map((op) => { - const isExpanded = - expandedOperations.indexOf(op.operationId) !== -1 - - return ( - - setOperationState(op.operationId, !isCollapsed) - } - /> - ) - })} -
- - ) : ( - <> -

- {info.title} -

-

- Select a service from the sidebar. -

- - ) - } - /> -
- ) -} - -export { getPathsFromSchema, getPropsForPage } -export default OpenApiPage diff --git a/website/components/openapi-page/index.props.js b/website/components/openapi-page/index.props.js deleted file mode 100644 index 92c651d83..000000000 --- a/website/components/openapi-page/index.props.js +++ /dev/null @@ -1,32 +0,0 @@ -import PropTypes from 'prop-types' -import OpenAPIPage from '.' - -function OpenAPIPageProps(props) { - return -} - -OpenAPIPageProps.propTypes = { - /** Information about the API, pulled from the schema's [Info Object](https://swagger.io/specification/v2/#info-object) */ - info: PropTypes.shape({ - title: PropTypes.string.isRequired, - description: PropTypes.string, - version: PropTypes.string, - }), - /** The name of the associated HashiCopr product, used in page metadata */ - productName: PropTypes.string, - /** The slug of the associated HashiCorp product, used for theming. Only supports "boundary" or a default theme at present.*/ - productSlug: PropTypes.oneOf(['boundary']), - /** An object that determines which operations will be shown on the page */ - operationCategory: PropTypes.shape({ - /** The name of the operation "category", used as the page title */ - name: PropTypes.string, - /** The slug-ified name, used as the page's location */ - slug: PropTypes.string, - /** An array of [Operation Objects](https://swagger.io/specification/v2/#operation-object) to be displayed on the page */ - operations: PropTypes.arrayOf(PropTypes.object), - }), - /** ["order"](https://github.com/hashicorp/react-components/blob/11d7bda7d518bc675ab0033067d43057e21f3b77/packages/docs-sidenav/index.js#L9) data generated to be passed directly to our DocsSidenav component */ - sidenavOrderData: PropTypes.object, -} - -export default OpenAPIPageProps diff --git a/website/components/openapi-page/partials/chevron-down/black.jsx b/website/components/openapi-page/partials/chevron-down/black.jsx deleted file mode 100644 index 2c7c0fa0c..000000000 --- a/website/components/openapi-page/partials/chevron-down/black.jsx +++ /dev/null @@ -1,23 +0,0 @@ -function ChevronDownBlack({ title, ...props }) { - return ( - - {title ? {title} : null} - - - ) -} - -export default ChevronDownBlack diff --git a/website/components/openapi-page/partials/collapsible/collapsible.module.css b/website/components/openapi-page/partials/collapsible/collapsible.module.css deleted file mode 100644 index a2ad211a2..000000000 --- a/website/components/openapi-page/partials/collapsible/collapsible.module.css +++ /dev/null @@ -1,18 +0,0 @@ -.outer { - overflow: hidden; - height: 0; - &[data-useanimation='true'] { - transition: height 0.4s; - } -} - -.inner { - opacity: 1; - - &[data-iscollapsed='true'] { - opacity: 0; - } - &[data-useanimation='true'] { - transition: opacity 0.4s; - } -} diff --git a/website/components/openapi-page/partials/collapsible/index.js b/website/components/openapi-page/partials/collapsible/index.js deleted file mode 100644 index 673d8111d..000000000 --- a/website/components/openapi-page/partials/collapsible/index.js +++ /dev/null @@ -1,81 +0,0 @@ -import { Component } from 'react' -import styles from './collapsible.module.css' - -/* - Collapsible content block, receives children and a 'isCollapsed' prop, - smoothly animates from collapsed (height 0) to expanded (height auto) -*/ -export default class Collapsible extends Component { - constructor(props) { - super(props) - this.animateHeight = this.animateHeight.bind(this) - } - - componentDidMount() { - this.animateHeight() - } - - componentDidUpdate(prevProps) { - // Only update if isCollapsed prop has changed - if (this.props.isCollapsed === prevProps.isCollapsed) return - this.animateHeight() - } - - animateHeight() { - function handleTransitionEnd(event) { - const elem = event.target - const elemStyle = getComputedStyle(elem) - const isCollapsed = elem.getAttribute('data-iscollapsed') - if (event.propertyName !== 'height') return - const innerElem = event.target.firstChild - const innerElemStyle = getComputedStyle(innerElem) - if (isCollapsed === 'false') { - elem.style.height = 'auto' - innerElem.style.transitionDelay = '0s' - } else if (isCollapsed === 'true') { - const heightDurn = parseFloat(elemStyle['transition-duration']) - const opactiyDurn = parseFloat(innerElemStyle['transition-duration']) - innerElem.style.transitionDelay = `${heightDurn - opactiyDurn}s` - } - elem.removeEventListener('transitionend', handleTransitionEnd, false) - } - const { isCollapsed } = this.props - // Do not attempt update if container elem is invalid - const elem = this.containerRef - if (!elem) return - const elemStyle = getComputedStyle(elem) - if (isCollapsed) { - // Transition from auto to 0 - elem.style.height = elemStyle.height - elem.offsetHeight // force repaint - elem.style.height = '0px' - elem.setAttribute('data-iscollapsed', 'true') - elem.addEventListener('transitionend', handleTransitionEnd, false) - } else { - // Transition from 0 to auto - const prevHeight = elem.style.height - elem.style.height = 'auto' - const endHeight = elemStyle.height - elem.style.height = prevHeight - elem.offsetHeight // force repaint - elem.style.height = endHeight - elem.setAttribute('data-iscollapsed', 'false') - elem.addEventListener('transitionend', handleTransitionEnd, false) - } - } - - render() { - const { children, noAnimation } = this.props - return ( -
(this.containerRef = ref)} - data-useanimation={Boolean(!noAnimation)} - > -
- {children} -
-
- ) - } -} diff --git a/website/components/openapi-page/partials/operation-object/index.js b/website/components/openapi-page/partials/operation-object/index.js deleted file mode 100644 index 2c6a87373..000000000 --- a/website/components/openapi-page/partials/operation-object/index.js +++ /dev/null @@ -1,154 +0,0 @@ -import Collapsible from '../collapsible' -import ResponseObject from '../response-object' -import PropertyObject from '../property-object' -import { capitalCase } from 'change-case' -import useHover from '../../../../lib/hooks/use-hover' -import SvgrChevronDown from '../chevron-down/black' - -import styles from './operation-object.module.css' - -function OperationObject({ - data, - path, - type, - isHighlighted, - isCollapsed, - setIsCollapsed, -}) { - const [headerRef, isHeaderHovered] = useHover() - - // const [isCollapsed, setIsCollapsed] = useState(true) - const { operationId, parameters, responses, summary } = data - const successResponse = responses['200'] - const title = capitalCase(operationId.split('_').slice(1).join()) - - // Group parameter properties by type - const pathParams = parameters.filter((p) => p.in === 'path') - const queryParams = parameters.filter((p) => p.in === 'query') - const bodyParam = parameters.filter((p) => p.in === 'body')[0] // Note: we only accept a single "in=body" param - const bodyProps = bodyParam ? getBodyParamProps(bodyParam) : [] - - return ( -
-
setIsCollapsed(!isCollapsed)} - > -
-
- {title} -
-
- - {type.toUpperCase()}{' '} - - {path} -
-
-
- - {isCollapsed ? 'Expand' : 'Collapse'} - - - - -
-
- -
-

{summary}

- -

Request

- {pathParams.length > 0 ? ( - - ) : null} - {queryParams.length > 0 ? ( - - ) : null} - {bodyProps.length > 0 ? ( - - ) : null} -
- } - columnTwo={ -
-

Response

- {!!successResponse ? ( -
-

- Successful Response -

- -
- ) : ( -

No response has been defined.

- )} -
- } - /> -
- - - ) -} - -function getBodyParamProps(bodyParam) { - // We always expect the bodyParam to be an object, - // with a schema which defines the body properties. - if (!bodyParam.schema || !bodyParam.schema.properties) return [] - // We flatten these properties to avoid showing a - // "collapsed object" UI under the "Body Parameters" section, - // which would be a bit redundant and annoying to have to expand - const bodyPropsObj = bodyParam.schema.properties - const bodyProps = Object.keys(bodyPropsObj).reduce((acc, key) => { - const data = Object.assign({}, bodyPropsObj[key]) - // We need the property name. This is usually be handled by "key" in an object, - // but we're flattening the object so we need to make sure it's there - data.name = key - if (!data.readOnly) acc.push(data) - return acc - }, []) - return bodyProps -} - -function TwoColumnLayout({ columnOne, columnTwo }) { - return ( -
-
{columnOne}
-
-
{columnTwo}
-
- ) -} - -function Parameters({ title, params }) { - return ( -
-

- {title} -

- {params.map((parameter, idx) => { - return ( - - ) - })} -
- ) -} - -export default OperationObject diff --git a/website/components/openapi-page/partials/operation-object/index.props.js b/website/components/openapi-page/partials/operation-object/index.props.js deleted file mode 100644 index a414821d5..000000000 --- a/website/components/openapi-page/partials/operation-object/index.props.js +++ /dev/null @@ -1,61 +0,0 @@ -import React from 'react' -import PropTypes from 'prop-types' -import OperationObject from '.' - -function OperationObjectProps(props) { - return -} - -/** Displays [Operation Object](https://swagger.io/specification/v2/#operation-object) data to the user. */ -OperationObjectProps.propTypes = { - /** The path to the endpoint where this operation is executed */ - path: PropTypes.string.isRequired, - /** The type of operation */ - type: PropTypes.oneOf([ - 'get', - 'put', - 'post', - 'delete', - 'options', - 'head', - 'patch', - ]).isRequired, - /** A subset of [Operation Object](https://swagger.io/specification/v2/#operation-object) relevant to the UI */ - data: PropTypes.shape({ - /** Flag whether this operation is deprecated */ - deprecated: PropTypes.bool, - /** A unique string used to identify the operation.*/ - operationId: PropTypes.string, - /** Array of parameter objects. We group them by their "in" property, and pass them to the component for rendering. */ - parameters: PropTypes.arrayOf( - PropTypes.shape({ - /** The name of the parameter. Parameter names are case sensitive. */ - name: PropTypes.string.isRequired, - /** A brief, plain text description of the parameter. Note that [GitHub-flavor markdown](https://guides.github.com/features/mastering-markdown/#GitHub-flavored-markdown) is not currently supported. */ - description: PropTypes.string, - /** Indicates whether this parameter is mandatory. */ - required: PropTypes.boolean, - /** The location of the parameter. Note: `formData` and `header` are not currently supported in the UI. */ - in: PropTypes.oneOf(['query', 'path', 'body']).isRequired, - /** Schema is used for "body" parameters. */ - schema: PropTypes.object, - /** Type defines the parameter type, for non-"body" parameters. */ - type: PropTypes.oneOf([ - 'array', - 'boolean', - 'integer', - 'number', - 'object', - 'string', - ]), - }) - ), - /** Responses object, keys are HTTP response codes */ - responses: PropTypes.shape({ - /** We only support "200" response codes, for now. This object is passed to the component. */ - 200: PropTypes.object, - }), - }), -} - -export default OperationObjectProps diff --git a/website/components/openapi-page/partials/operation-object/operation-object.module.css b/website/components/openapi-page/partials/operation-object/operation-object.module.css deleted file mode 100644 index 93bea1984..000000000 --- a/website/components/openapi-page/partials/operation-object/operation-object.module.css +++ /dev/null @@ -1,145 +0,0 @@ -.root { - border-bottom: 1px solid var(--gray-5); - margin: 0; - margin-top: -1px; - position: relative; - transition: border-color 0.2s; - - &[data-is-hovered='true'] { - border-bottom-color: var(--brand); - z-index: 1; - } -} - -.header { - display: flex; - position: relative; - padding: 16px 0; - - &:hover { - cursor: pointer; - } -} - -.meta { - width: 100%; -} - -.title { - position: relative; - display: inline-block; - composes: g-type-body-x-strong from global; - color: var(--gray-2); - margin: 0 0 4px 0; - padding: 0; - - &[data-is-highlighted='true'] { - &::before { - content: '\200B'; - position: absolute; - top: -4px; - left: -8px; - right: -8px; - bottom: -4px; - background: var(--warning-l1); - z-index: -1; - border-radius: 8px; - } - } - - &[data-is-hovered='true'] { - color: var(--brand); - } -} - -.endpoint { - composes: g-type-code from global; - - & .method { - color: var(--gray-3); - - &[data-is-hovered='true'] { - color: var(--brand); - } - } - - & .path { - color: var(--gray-2); - } -} - -.toggleButton { - border: none; - color: var(--brand); - background: none; - display: flex; - align-items: center; - font-size: inherit; - margin: 0; - padding: 0 0 0 24px; - transition: color 0.2s; - - & .toggleIcon { - width: 16px; - height: 16px; - margin-left: 8px; - position: relative; - top: 1px; - transition: transform 0.3s; - display: flex; - align-items: center; - justify-content: center; - - & svg { - & [fill] { - fill: var(--brand); - } - & [stroke] { - stroke: var(--brand); - } - } - - &[data-is-collapsed='false'] { - transform: rotate(-180deg); - } - } - - &[data-is-hovered='true'] { - color: var(--brand); - } -} - -.details { - padding-bottom: 80px; - - & .summary { - color: var(--gray-2); - margin: 8px 0 24px 0; - } - - & .columnHeading { - margin: 0 0 1em 0; - font-weight: bold; - } - - & .columnSectionHeading { - margin: 0 !important; /* Needed to override ".g-content p" margins */ - padding-bottom: 8px; - border-bottom: 1px solid var(--gray-5); - color: var(--gray-3); - } -} - -.twoColumnLayout { - display: flex; - - & > div:nth-child(1), - & > div:nth-child(3) { - position: relative; - width: calc(50% - 16px); - } - - & > div:nth-child(2) { - width: 32px; - } -} diff --git a/website/components/openapi-page/partials/property-object/index.js b/website/components/openapi-page/partials/property-object/index.js deleted file mode 100644 index 63e672a20..000000000 --- a/website/components/openapi-page/partials/property-object/index.js +++ /dev/null @@ -1,91 +0,0 @@ -import { useState } from 'react' -import Collapsible from '../collapsible' -import SvgrChevronDown from '../chevron-down/black' -import styles from './property-object.module.css' - -function PropertyObject({ - name, - data, - isFirstItem, - isLastItem, - arrayDepth = 0, -}) { - const [isCollapsed, setIsCollapsed] = useState(true) - const isArray = data.type === 'array' - if (isArray) - return ( - - ) - const hasProperties = data.type === 'object' && Boolean(data.properties) - - const typeArraySuffix = - arrayDepth > 0 ? arrayFrom(arrayDepth, '[]').join('') : '' - const typeString = `${data.type}${typeArraySuffix}` - return ( -
- {name}{' '} - {typeString}{' '} - {data.required ? ( - - Required - - ) : null} - {data.title && ( -

{data.title}

- )} - {data.description && ( -

- {data.description} -

- )} - {hasProperties && ( -
- - -
- {Object.keys(data.properties).map((propertyKey, idx) => { - return ( - - ) - })} -
-
-
- )} -
- ) -} - -function arrayFrom(length, value = null) { - let array = [] - for (var i = 0; i < length; i++) { - array.push(value) - } - return array -} - -export default PropertyObject diff --git a/website/components/openapi-page/partials/property-object/property-object.module.css b/website/components/openapi-page/partials/property-object/property-object.module.css deleted file mode 100644 index c7f9a73f6..000000000 --- a/website/components/openapi-page/partials/property-object/property-object.module.css +++ /dev/null @@ -1,85 +0,0 @@ -.root { - border-top: 1px solid var(--gray-5); - border-bottom: 1px solid var(--gray-5); - padding: 16px 0; - margin: -1px 0 0 0; - - &[data-is-first-item='true'] { - border-top: none; - } - - &[data-is-last-item='true'] { - border-bottom: none; - } - - & .name { - color: var(--brand); - background: rgba(29, 30, 35, 0.07); - border-radius: 3px; - padding: 0.3em 0.625em; - } - - & .typeString { - color: var(--gray-2); - background: none; - padding: 0; - margin-left: 2px; - } - - & .requiredFlag { - color: var(--danger-d1); - margin-left: 4px; - } - - & .title, - & .description { - color: var(--gray-2); - margin: 8px 0 0 0; - } - - & .toggleButton { - border: 1px solid red; - border: none; - color: var(--brand); - background: none; - display: flex; - align-items: center; - margin: 8px 0 0 0; - padding: 0; - - & .toggleIcon { - position: relative; - top: 1px; - width: 16px; - height: 16px; - margin-right: 8px; - transition: transform 0.3s; - display: flex; - align-items: center; - justify-content: center; - - & svg { - & [fill] { - fill: var(--brand); - } - & [stroke] { - stroke: var(--brand); - } - } - - &[data-is-collapsed='false'] { - transform: rotate(-180deg); - } - } - - &:hover { - cursor: pointer; - } - } - - & .propertiesContainer { - margin: 8px 0 0 8px; - padding-left: 16px; - border-left: 1px solid var(--gray-5); - } -} diff --git a/website/components/openapi-page/partials/response-object/index.js b/website/components/openapi-page/partials/response-object/index.js deleted file mode 100644 index 4d39fe833..000000000 --- a/website/components/openapi-page/partials/response-object/index.js +++ /dev/null @@ -1,27 +0,0 @@ -import PropertyObject from '../property-object' - -function ResponseObject({ data }) { - // `schema` can be empty, which means the response does not return content - // We currently only support object responses (ie those that have schema.properties) in the UI - // Ref: https://swagger.io/specification/v2/#response-object - if (!data || !data.schema || !data.schema.properties) { - return
No content.
- } - return ( -
- {Object.keys(data.schema.properties).map((propertyKey, idx) => { - return ( - - ) - })} -
- ) -} - -export default ResponseObject diff --git a/website/components/openapi-page/partials/response-object/index.props.js b/website/components/openapi-page/partials/response-object/index.props.js deleted file mode 100644 index 8ed469813..000000000 --- a/website/components/openapi-page/partials/response-object/index.props.js +++ /dev/null @@ -1,16 +0,0 @@ -import PropTypes from 'prop-types' -import ResponseObject from '.' - -function ResponseObjectProps(props) { - return -} - -ResponseObjectProps.propTypes = { - /** [Response Object](https://swagger.io/specification/v2/#response-object) data. */ - data: PropTypes.shape({ - /** A [Schema Object](https://swagger.io/specification/v2/#schema-object) that describes the response. Note that we currently only support objects (with schema.properties) responses in the UI. */ - schema: PropTypes.object, - }), -} - -export default ResponseObjectProps diff --git a/website/components/openapi-page/style.module.css b/website/components/openapi-page/style.module.css deleted file mode 100644 index 52da68316..000000000 --- a/website/components/openapi-page/style.module.css +++ /dev/null @@ -1,57 +0,0 @@ -.root { - composes: g-grid-container from global; - display: flex; - flex-direction: column; - flex: 1 0 auto; - position: relative; - width: 100%; - - @media (min-width: 940px) { - flex-direction: row; - margin-bottom: 24px; - margin-top: 72px; - } - - /* currently only supports "boundary", may want to extend to support other product themes */ - &[data-theme='boundary'] { - --brand: var(--boundary); - } - - & .pageHeading { - margin: 0; - } - - & .categoryHeading { - margin: 32px 0 16px 0; - } - - & :global(.g-content) { - padding-left: 0; - padding-right: 0; - margin: 0; - - @media (max-width: 939px) { - padding-left: 0; - padding-right: 0; - margin-top: 64px; - } - - & > h1:first-child { - margin-top: 0; - } - } - - & :global(.g-section-header) { - margin-bottom: 100px; - } - - /* TODO: this should be applied in global styles, temporary override here */ - & pre, - & code { - font-size: 0.875em; - } - - & pre code { - font-size: 1em; - } -} diff --git a/website/components/openapi-page/utils/routing-utils.js b/website/components/openapi-page/utils/routing-utils.js deleted file mode 100644 index 0bffdaa88..000000000 --- a/website/components/openapi-page/utils/routing-utils.js +++ /dev/null @@ -1,121 +0,0 @@ -import { capitalCase } from 'change-case' -import slugify from '@hashicorp/remark-plugins/generate_slug' - -/* Gieven a schema, current service slug, and parentPath, return all props needed for an openapi component page */ -export function getPropsForPage(schema, params) { - // parse the data we'll show to the user from the schema - const operationObjects = getOperationObjects(schema) - const serviceIds = getServiceIds(operationObjects) - // info and sidenav data are needed on all pages - const info = schema.info - const navData = getSidenavData(serviceIds) - // If there's no "page" param, then this is the landing page - const isLanding = !params || !params.page || params.page.length == 0 - - const currentPath = params && params.page ? params.page.join('/') : '' - - // Otherwise, we should have an operationCategory that matches the slug-ified ID from the URL path - const operationCategory = isLanding - ? false - : serviceIds - .filter((id) => getServiceSlug(id) === params.page[0]) - .map((serviceId) => { - const name = capitalCase(serviceId) - const slug = getServiceSlug(serviceId) - const operations = operationObjects.filter( - (o) => getServiceId(o.operationId) === serviceId - ) - return { name, slug, operations } - })[0] - - return { info, navData, operationCategory, currentPath } -} - -/* Given a schema, return all the paths we'll render for our openapi generated docs */ -export function getPathsFromSchema(schema) { - // Assign each operation category to a URL using its slug-ified ID - const operationObjects = getOperationObjects(schema) - const slugs = getServiceIds(operationObjects).map(getServiceSlug) - // We need a path for each "service" - const paths = slugs.map((slug) => ({ params: { page: [slug] } })) - // We also push a path for an "/" index page - paths.push({ params: { page: [] } }) - return paths -} - -/* Given a list of service ids, return an object suitable to pass to -to render a flat list of services */ -function getSidenavData(serviceIds) { - const order = serviceIds.map((serviceId) => { - return { - title: capitalCase(serviceId), - indexData: true, - path: getServiceSlug(serviceId), - } - }) - return order -} - -/* Given a serviceId, which is typically PascalCase string, return a slugified kebab-case string (ie: pascal-case rather than pascalcase) */ -function getServiceSlug(serviceId) { - return slugify(capitalCase(serviceId)) -} - -/* Given an operationId, return the "serviceId" */ -function getServiceId(operationId) { - // We expect operationIds to have two parts, separated by an underscore - // The "serviceId" is the first part of the value - return operationId.split('_')[0] -} - -/* Given a schema, return an array of unique operation "category" strings */ -export function getServiceIds(operationObjects) { - const operationIdCategories = operationObjects - .map((o) => getServiceId(o.operationId)) - .sort() - // Several related operationIds may have the same "category" part, - // so we filter for unique values before returning - return filterUnique(operationIdCategories) -} - -/* Given an array of values, return an array without duplicate items */ -function filterUnique(array) { - return array.filter((value, idx) => array.indexOf(value) === idx) -} - -/* Given a schema, return a flattened list of operation objects */ -function getOperationObjects(schema) { - const pathItemObjects = Object.keys(schema.paths).reduce((acc, path) => { - acc.push({ __path: path, ...schema.paths[path] }) - return acc - }, []) - - const operationObjects = pathItemObjects.reduce((acc, pathItemObject) => { - // Each path can support many operations through different request types - const requestTypes = [ - 'get', - 'put', - 'post', - 'delete', - 'options', - 'head', - 'patch', - ] - const pathOperations = requestTypes.reduce((acc, type) => { - // Not all paths will support every request type - if (!pathItemObject[type]) return acc - // If the request type is supported, push the associated operation - acc.push({ - __type: type, - __path: pathItemObject.__path, - ...pathItemObject[type], - }) - return acc - }, []) - return acc.concat(pathOperations) - }, []) - - return operationObjects -} - -export default getPathsFromSchema diff --git a/website/package-lock.json b/website/package-lock.json index 561a5be85..0b24b5899 100644 --- a/website/package-lock.json +++ b/website/package-lock.json @@ -26,6 +26,7 @@ "@hashicorp/react-hero": "^8.0.2", "@hashicorp/react-image": "^4.0.3", "@hashicorp/react-markdown-page": "^1.4.3", + "@hashicorp/react-open-api-page": "^2.0.1", "@hashicorp/react-product-downloads-page": "^2.5.2", "@hashicorp/react-product-features-list": "^5.0.0", "@hashicorp/react-search": "^6.1.1", @@ -877,6 +878,11 @@ "resolved": "https://registry.npmjs.org/@hapi/hoek/-/hoek-9.2.0.tgz", "integrity": "sha512-sqKVVVOe5ivCaXDWivIJYVSaEgdQK9ul7a4Kity5Iw7u9+wBAPbX1RMSnLLmp7O4Vzj0WOWwMAJsTL00xwaNug==" }, + "node_modules/@hashicorp/flight-icons": { + "version": "1.2.0", + "resolved": "https://registry.npmjs.org/@hashicorp/flight-icons/-/flight-icons-1.2.0.tgz", + "integrity": "sha512-gMsPGbDXSBWe4v7sFjG+ZlQdc8ipNLi5w98muaKU5tUNG027b5XNy5chkiT1/gsygi5ZlKXU0klgC0JHZ44B8A==" + }, "node_modules/@hashicorp/js-utils": { "version": "1.0.10", "resolved": "https://registry.npmjs.org/@hashicorp/js-utils/-/js-utils-1.0.10.tgz", @@ -1199,9 +1205,9 @@ "integrity": "sha512-OlQdbZ7gLfGarSqxesMesDa5uz7KFbID8Kpq/SxIoNGDqY8lSYs0D+hhtBXhcdB3rcbXArFr7vlHheLk1voeNA==" }, "node_modules/@hashicorp/react-content": { - "version": "8.0.2", - "resolved": "https://registry.npmjs.org/@hashicorp/react-content/-/react-content-8.0.2.tgz", - "integrity": "sha512-FNE1IiXizUDPL/rsvo37uYSBsAB8LhtCianMU/h3MIj8Khcwc/qC3pTabGs9Kv3ujA+fiIp/ImzWEGAhB22T7g==", + "version": "8.0.3", + "resolved": "https://registry.npmjs.org/@hashicorp/react-content/-/react-content-8.0.3.tgz", + "integrity": "sha512-WSmTlU3UU0YMbp1Eb9RCZqWh4skwIeXPQY/OFaNLgZqQh6/vP+j7c6pItPhnSz8w0u81XatuxVfo0cJjtxidYg==", "dependencies": { "@hashicorp/platform-product-meta": "^0.1.0", "classnames": "^2.3.1" @@ -1446,6 +1452,26 @@ "react": ">=16.x" } }, + "node_modules/@hashicorp/react-open-api-page": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/@hashicorp/react-open-api-page/-/react-open-api-page-2.0.1.tgz", + "integrity": "sha512-9D1rAKksUyvrdsKFA/uR54jFSO4egr8np6X8ayIPSRUSCbIqLNKl46MitXf9oddqL3xunaN2dL/cjqQ7FYycPA==", + "dependencies": { + "@apidevtools/json-schema-ref-parser": "^9.0.9", + "@hashicorp/flight-icons": "^1.1.0", + "@hashicorp/platform-markdown-utils": "^0.1.3", + "@hashicorp/react-content": "^8.0.3", + "@hashicorp/react-docs-sidenav": "^8.4.0", + "@hashicorp/react-head": "^3.1.2", + "change-case": "^4.1.2", + "classnames": "^2.3.1" + } + }, + "node_modules/@hashicorp/react-open-api-page/node_modules/classnames": { + "version": "2.3.1", + "resolved": "https://registry.npmjs.org/classnames/-/classnames-2.3.1.tgz", + "integrity": "sha512-OlQdbZ7gLfGarSqxesMesDa5uz7KFbID8Kpq/SxIoNGDqY8lSYs0D+hhtBXhcdB3rcbXArFr7vlHheLk1voeNA==" + }, "node_modules/@hashicorp/react-placeholder": { "version": "0.1.0", "resolved": "https://registry.npmjs.org/@hashicorp/react-placeholder/-/react-placeholder-0.1.0.tgz", @@ -4443,7 +4469,7 @@ "integrity": "sha1-5aSs0sEB/fPZpNB/DbxNtJ3SgXY=", "dev": true, "engines": { - "node": ">=4" + "node": ">=6" } }, "node_modules/bin-wrapper/node_modules/file-type": { @@ -4515,6 +4541,9 @@ "resolved": "https://registry.npmjs.org/p-cancelable/-/p-cancelable-0.4.1.tgz", "integrity": "sha512-HNa1A8LvB1kie7cERyy21VNeHb2CWJJYqyyC2o3klWFfMGlFmWv2Z7sFgZH8ZiaYL95ydToKTFVXgMV/Os0bBQ==", "dev": true, + "dependencies": { + "p-timeout": "^2.0.1" + }, "engines": { "node": ">=4" } @@ -7296,7 +7325,7 @@ "esutils": "^2.0.2" }, "engines": { - "node": ">=0.10.0" + "node": ">=4" } }, "node_modules/eslint-plugin-import/node_modules/hosted-git-info": { @@ -8272,7 +8301,7 @@ "version": "3.19.0", "resolved": "https://registry.npmjs.org/fast-xml-parser/-/fast-xml-parser-3.19.0.tgz", "integrity": "sha512-4pXwmBplsCPv8FOY1WRakF970TjNGnGnfbOnLqjlYvMiF1SR3yOHyxMR/YCXpPTOspNF5gwudqktIP4VsWkvBg==", - "dev": true, + "devOptional": true, "bin": { "xml2js": "cli.js" }, @@ -8506,7 +8535,10 @@ "locate-path": "^2.0.0" }, "engines": { - "node": ">=4" + "node": ">=8" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" } }, "node_modules/find-versions": { @@ -10372,7 +10404,10 @@ "kind-of": "^6.0.0" }, "engines": { - "node": ">=0.10.0" + "node": ">= 0.4" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" } }, "node_modules/is-date-object": { @@ -10584,10 +10619,13 @@ "integrity": "sha512-h5PpgXkWitc38BBMYawTYMWJHFZJVnBquFE57xFpjB8pJFiF6gZ+bU+WyI/yqXiFR5mdLsgYNaPe8uao6Uv9Og==", "devOptional": true, "dependencies": { - "isobject": "^3.0.1" + "fast-xml-parser": "^3.19.0" }, "engines": { - "node": ">=0.10.0" + "node": ">=6" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" } }, "node_modules/is-png": { @@ -10657,14 +10695,8 @@ "resolved": "https://registry.npmjs.org/is-svg/-/is-svg-4.3.1.tgz", "integrity": "sha512-h2CGs+yPUyvkgTJQS9cJzo9lYK06WgRiXUqBBHtglSzVKAuH4/oWsqk7LGfbSa1hGk9QcZ0SyQtVggvBA8LZXA==", "dev": true, - "dependencies": { - "fast-xml-parser": "^3.19.0" - }, - "engines": { - "node": ">=6" - }, "funding": { - "url": "https://github.com/sponsors/sindresorhus" + "url": "https://github.com/sponsors/ljharb" } }, "node_modules/is-symbol": { @@ -10888,7 +10920,10 @@ "resolved": "https://registry.npmjs.org/has-flag/-/has-flag-4.0.0.tgz", "integrity": "sha512-EykJT/Q1KjTWctppgIAgfSO0tKVuZUjhgMr17kqTumMl6Afv3EISleU7qZUzoXDFTAHTDC4NOoG/ZxU3EvlMPQ==", "engines": { - "node": ">=8" + "node": ">=10" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" } }, "node_modules/jest-worker/node_modules/supports-color": { @@ -11205,8 +11240,8 @@ "engines": { "node": ">=10" }, - "funding": { - "url": "https://github.com/sponsors/sindresorhus" + "optionalDependencies": { + "graceful-fs": "^4.1.6" } }, "node_modules/lint-staged/node_modules/has-flag": { @@ -12379,7 +12414,7 @@ "is-extendable": "^1.0.1" }, "engines": { - "node": ">=0.10.0" + "node": ">=4.0.0" } }, "node_modules/mixin-deep/node_modules/is-extendable": { @@ -20957,6 +20992,11 @@ "resolved": "https://registry.npmjs.org/@hapi/hoek/-/hoek-9.2.0.tgz", "integrity": "sha512-sqKVVVOe5ivCaXDWivIJYVSaEgdQK9ul7a4Kity5Iw7u9+wBAPbX1RMSnLLmp7O4Vzj0WOWwMAJsTL00xwaNug==" }, + "@hashicorp/flight-icons": { + "version": "1.2.0", + "resolved": "https://registry.npmjs.org/@hashicorp/flight-icons/-/flight-icons-1.2.0.tgz", + "integrity": "sha512-gMsPGbDXSBWe4v7sFjG+ZlQdc8ipNLi5w98muaKU5tUNG027b5XNy5chkiT1/gsygi5ZlKXU0klgC0JHZ44B8A==" + }, "@hashicorp/js-utils": { "version": "1.0.10", "resolved": "https://registry.npmjs.org/@hashicorp/js-utils/-/js-utils-1.0.10.tgz", @@ -21232,9 +21272,9 @@ } }, "@hashicorp/react-content": { - "version": "8.0.2", - "resolved": "https://registry.npmjs.org/@hashicorp/react-content/-/react-content-8.0.2.tgz", - "integrity": "sha512-FNE1IiXizUDPL/rsvo37uYSBsAB8LhtCianMU/h3MIj8Khcwc/qC3pTabGs9Kv3ujA+fiIp/ImzWEGAhB22T7g==", + "version": "8.0.3", + "resolved": "https://registry.npmjs.org/@hashicorp/react-content/-/react-content-8.0.3.tgz", + "integrity": "sha512-WSmTlU3UU0YMbp1Eb9RCZqWh4skwIeXPQY/OFaNLgZqQh6/vP+j7c6pItPhnSz8w0u81XatuxVfo0cJjtxidYg==", "requires": { "@hashicorp/platform-product-meta": "^0.1.0", "classnames": "^2.3.1" @@ -21432,6 +21472,28 @@ "gray-matter": "4.0.2" } }, + "@hashicorp/react-open-api-page": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/@hashicorp/react-open-api-page/-/react-open-api-page-2.0.1.tgz", + "integrity": "sha512-9D1rAKksUyvrdsKFA/uR54jFSO4egr8np6X8ayIPSRUSCbIqLNKl46MitXf9oddqL3xunaN2dL/cjqQ7FYycPA==", + "requires": { + "@apidevtools/json-schema-ref-parser": "^9.0.9", + "@hashicorp/flight-icons": "^1.1.0", + "@hashicorp/platform-markdown-utils": "^0.1.3", + "@hashicorp/react-content": "^8.0.3", + "@hashicorp/react-docs-sidenav": "^8.4.0", + "@hashicorp/react-head": "^3.1.2", + "change-case": "^4.1.2", + "classnames": "^2.3.1" + }, + "dependencies": { + "classnames": { + "version": "2.3.1", + "resolved": "https://registry.npmjs.org/classnames/-/classnames-2.3.1.tgz", + "integrity": "sha512-OlQdbZ7gLfGarSqxesMesDa5uz7KFbID8Kpq/SxIoNGDqY8lSYs0D+hhtBXhcdB3rcbXArFr7vlHheLk1voeNA==" + } + } + }, "@hashicorp/react-placeholder": { "version": "0.1.0", "resolved": "https://registry.npmjs.org/@hashicorp/react-placeholder/-/react-placeholder-0.1.0.tgz", @@ -23891,7 +23953,10 @@ "version": "0.4.1", "resolved": "https://registry.npmjs.org/p-cancelable/-/p-cancelable-0.4.1.tgz", "integrity": "sha512-HNa1A8LvB1kie7cERyy21VNeHb2CWJJYqyyC2o3klWFfMGlFmWv2Z7sFgZH8ZiaYL95ydToKTFVXgMV/Os0bBQ==", - "dev": true + "dev": true, + "requires": { + "p-timeout": "^2.0.1" + } }, "p-event": { "version": "2.3.1", @@ -26937,7 +27002,7 @@ "version": "3.19.0", "resolved": "https://registry.npmjs.org/fast-xml-parser/-/fast-xml-parser-3.19.0.tgz", "integrity": "sha512-4pXwmBplsCPv8FOY1WRakF970TjNGnGnfbOnLqjlYvMiF1SR3yOHyxMR/YCXpPTOspNF5gwudqktIP4VsWkvBg==", - "dev": true + "devOptional": true }, "fastest-levenshtein": { "version": "1.0.12", @@ -28704,7 +28769,7 @@ "integrity": "sha512-h5PpgXkWitc38BBMYawTYMWJHFZJVnBquFE57xFpjB8pJFiF6gZ+bU+WyI/yqXiFR5mdLsgYNaPe8uao6Uv9Og==", "devOptional": true, "requires": { - "isobject": "^3.0.1" + "fast-xml-parser": "^3.19.0" } }, "is-png": { @@ -28749,10 +28814,7 @@ "version": "4.3.1", "resolved": "https://registry.npmjs.org/is-svg/-/is-svg-4.3.1.tgz", "integrity": "sha512-h2CGs+yPUyvkgTJQS9cJzo9lYK06WgRiXUqBBHtglSzVKAuH4/oWsqk7LGfbSa1hGk9QcZ0SyQtVggvBA8LZXA==", - "dev": true, - "requires": { - "fast-xml-parser": "^3.19.0" - } + "dev": true }, "is-symbol": { "version": "1.0.4", @@ -29169,7 +29231,10 @@ "version": "6.0.1", "resolved": "https://registry.npmjs.org/get-stream/-/get-stream-6.0.1.tgz", "integrity": "sha512-ts6Wi+2j3jQjqi70w5AlN8DFnkSwC+MqmxEzdEALB2qXZYV3X/b1CTfgPLGJNMeAWxdPfU8FO1ms3NUfaHCPYg==", - "dev": true + "dev": true, + "requires": { + "graceful-fs": "^4.1.6" + } }, "has-flag": { "version": "4.0.0", diff --git a/website/package.json b/website/package.json index c2b6cd3ff..4e787564e 100644 --- a/website/package.json +++ b/website/package.json @@ -22,6 +22,7 @@ "@hashicorp/react-hero": "^8.0.2", "@hashicorp/react-image": "^4.0.3", "@hashicorp/react-markdown-page": "^1.4.3", + "@hashicorp/react-open-api-page": "^2.0.1", "@hashicorp/react-product-downloads-page": "^2.5.2", "@hashicorp/react-product-features-list": "^5.0.0", "@hashicorp/react-search": "^6.1.1", diff --git a/website/pages/api-docs/[[...page]].jsx b/website/pages/api-docs/[[...page]].jsx index eb752b15f..4fa73554f 100644 --- a/website/pages/api-docs/[[...page]].jsx +++ b/website/pages/api-docs/[[...page]].jsx @@ -1,10 +1,12 @@ import { productName, productSlug } from 'data/metadata' +import OpenApiPage from '@hashicorp/react-open-api-page' +/* Used server-side only */ import path from 'path' -import parseSwagger from '../../lib/swagger-parser' -import OpenApiPage, { +import { getPathsFromSchema, getPropsForPage, -} from '../../components/openapi-page' +} from '@hashicorp/react-open-api-page/server' +import { processSchemaFile } from '@hashicorp/react-open-api-page/process-schema' const targetFile = '../internal/gen/controller.swagger.json' const pathFromRoot = 'api-docs' @@ -15,19 +17,21 @@ export default function OpenApiDocsPage(props) { {...props} productName={productName} productSlug={productSlug} - pathFromRoot={pathFromRoot} + baseRoute={pathFromRoot} /> ) } export async function getStaticPaths() { - const schema = await parseSwagger(path.join(process.cwd(), targetFile)) + const swaggerFile = path.join(process.cwd(), targetFile) + const schema = await processSchemaFile(swaggerFile) const paths = getPathsFromSchema(schema) return { paths, fallback: false } } export async function getStaticProps({ params }) { - const schema = await parseSwagger(path.join(process.cwd(), targetFile)) + const swaggerFile = path.join(process.cwd(), targetFile) + const schema = await processSchemaFile(swaggerFile) const props = getPropsForPage(schema, params) return { props } }