diff --git a/components/parameter-table/ChildBodyParametersRows.module.scss b/components/parameter-table/ChildBodyParametersRows.module.scss
new file mode 100644
index 0000000000..dd2631c562
--- /dev/null
+++ b/components/parameter-table/ChildBodyParametersRows.module.scss
@@ -0,0 +1,21 @@
+.childBodyParametersRows {
+ details tr {
+ border-top: none;
+ }
+
+ // Remove any default markdown article padding for property cells
+ details tr td {
+ padding-bottom: 0.25rem;
+ }
+
+ // Set the left border for in the nested property tables. Also need to override
+ // a default markdown file style that sets a table's font size based on
+ // percentage which would cause the table font size to shrink more and more
+ // as the properties nested more and more.
+ td {
+ table {
+ border-left: 4px solid var(--color-border-muted);
+ font-size: inherit !important;
+ }
+ }
+}
diff --git a/components/rest/ChildBodyParametersRows.tsx b/components/parameter-table/ChildBodyParametersRows.tsx
similarity index 63%
rename from components/rest/ChildBodyParametersRows.tsx
rename to components/parameter-table/ChildBodyParametersRows.tsx
index 959fb45ed5..6684846f4b 100644
--- a/components/rest/ChildBodyParametersRows.tsx
+++ b/components/parameter-table/ChildBodyParametersRows.tsx
@@ -1,7 +1,11 @@
+import cx from 'classnames'
+
import { useTranslation } from 'components/hooks/useTranslation'
import { ParameterRow } from './ParameterRow'
import type { ChildParameter } from './types'
+import styles from './ChildBodyParametersRows.module.scss'
+
type Props = {
slug: string
childParamsGroups: ChildParameter[]
@@ -15,27 +19,23 @@ export function ChildBodyParametersRows({
parentType,
childParamsGroups,
}: Props) {
- const { t } = useTranslation('products')
+ const { t } = useTranslation(['parameter_table', 'products'])
return (
-
-
-
-
- Properties of the
- {parentName}
- {parentType}
-
+
+
+ Properties of {parentName}
- |
- {`${t('rest.reference.name')}, ${t('rest.reference.type')}, ${t(
- 'rest.reference.description'
- )}`}
- |
+ {`${t('name')}, ${t('type')}, ${t('description')}`} |
diff --git a/components/parameter-table/ParameterRow.tsx b/components/parameter-table/ParameterRow.tsx
new file mode 100644
index 0000000000..822f09d2c9
--- /dev/null
+++ b/components/parameter-table/ParameterRow.tsx
@@ -0,0 +1,94 @@
+import cx from 'classnames'
+
+import { useTranslation } from 'components/hooks/useTranslation'
+import { ChildBodyParametersRows } from './ChildBodyParametersRows'
+import type { ChildParameter } from './types'
+
+type Props = {
+ rowParams: ChildParameter
+ slug: string
+ numPreviews?: number
+ isChild?: boolean
+ rowIndex?: number
+}
+
+export function ParameterRow({
+ rowParams,
+ slug,
+ numPreviews = 0,
+ rowIndex = 0,
+ isChild = false,
+}: Props) {
+ const { t } = useTranslation(['parameter_table', 'products'])
+ return (
+ <>
+
+
+ 0 && isChild ? 'pt-3 border-top color-border-muted' : ''}`
+ )}
+ >
+
+ {rowParams.name}
+ {rowParams.type}
+ {rowParams.isRequired ? (
+ {t('required')}
+ ) : null}
+
+
+
+
+ {numPreviews > 0 && (
+
+ {numPreviews > 1 ? ` ${t('see_preview_notices')}` : ` ${t('see_preview_notice')}`}
+
+ )}
+
+ {rowParams.default && (
+
+ {t('default')}:
+ {rowParams.default}
+
+ )}
+ {rowParams.enum && rowParams.enum.length && (
+
+ {rowParams.enum.length > 1 ? (
+ <>
+ {t('enum_description_title')}:
+ {rowParams.enum.map((item, index, array) => (
+
+ {item}
+ {index !== array.length - 1 && ','}{' '}
+
+ ))}
+ >
+ ) : (
+ <>
+ {t('single_enum_description')}:
+
+ {rowParams.enum[0]}
+
+ >
+ )}
+
+ )}
+
+
+
+ |
+
+ {rowParams.childParamsGroups && rowParams.childParamsGroups.length > 0 && (
+
+ )}
+ >
+ )
+}
diff --git a/components/parameter-table/ParameterTable.module.scss b/components/parameter-table/ParameterTable.module.scss
new file mode 100644
index 0000000000..df83083f7f
--- /dev/null
+++ b/components/parameter-table/ParameterTable.module.scss
@@ -0,0 +1,20 @@
+.parameterTable {
+ // this is for the child parameter table row that contiains the top level
+ // properties details toggle element because we want it to match the
+ // background color of the top level parameter rows. We need the !important
+ // because the child parameter rows (the nested expanded properties) otherwise
+ // have the same background color.
+ & > tbody > tr {
+ background: var(--color-canvas-default) !important;
+ }
+
+ // also for the top level child parameter table row, we want the details toggle
+ // to align with the top level parameter rows. Child parameter rows have some
+ // left padding so they can indent as they nest but we don't want that in
+ // this case. We need the !important to override general default markdown
+ // article styling.
+ & > tbody > tr > td > details {
+ padding-left: 0px !important;
+ margin-bottom: 4px !important;
+ }
+}
diff --git a/components/rest/RestParameterTable.tsx b/components/parameter-table/ParameterTable.tsx
similarity index 63%
rename from components/rest/RestParameterTable.tsx
rename to components/parameter-table/ParameterTable.tsx
index 69ef3d93a0..a6c326f70f 100644
--- a/components/rest/RestParameterTable.tsx
+++ b/components/parameter-table/ParameterTable.tsx
@@ -2,68 +2,77 @@ import cx from 'classnames'
import { useTranslation } from 'components/hooks/useTranslation'
import { ParameterRow } from './ParameterRow'
-import { BodyParameter, Parameter } from './types'
+import { BodyParameter, ChildParameter, Parameter } from './types'
+
+import styles from './ParameterTable.module.scss'
type Props = {
slug: string
numPreviews: number
+ heading: string
+ headers: Array
parameters: Array
bodyParameters: Array
}
-export function RestParameterTable({ slug, numPreviews, parameters, bodyParameters }: Props) {
- const { t } = useTranslation('products')
+export function ParameterTable({
+ slug,
+ numPreviews,
+ heading = '',
+ headers = [],
+ parameters,
+ bodyParameters,
+}: Props) {
+ const { t } = useTranslation(['parameter_table', 'products'])
const queryParams = parameters.filter((param) => param.in === 'query')
const pathParams = parameters.filter((param) => param.in === 'path')
return (
<>
-
+ {heading && (
+
+ )}
+
- |
- {`${t('rest.reference.name')}, ${t('rest.reference.type')}, ${t(
- 'rest.reference.description'
- )}`}
- |
+ {`${t('name')}, ${t('type')}, ${t('description')}`} |
- Setting to application/vnd.github+json is recommended.`,
- isRequired: false,
- }}
- slug={slug}
- numPreviews={numPreviews}
- />
+ {headers.length > 0 && (
+ <>
+ {headers.map((header, index) => (
+
+ ))}
+ >
+ )}
+
{pathParams.length > 0 && (
<>
|
- {t('rest.reference.path')}
+ {t('path')}
|
- |
- {`${t('rest.reference.name')}, ${t('rest.reference.type')}, ${t(
- 'rest.reference.description'
- )}`}
- |
+ {`${t('name')}, ${t('type')}, ${t('description')}`} |
{pathParams.map((param, index) => (
|
- {t('rest.reference.query')}
+ {t('query')}
|
- |
- {`${t('rest.reference.name')}, ${t('rest.reference.type')}, ${t(
- 'rest.reference.description'
- )}`}
- |
+ {`${t('name')}, ${t('type')}, ${t('description')}`} |
{queryParams.map((param, index) => (
@@ -118,15 +123,11 @@ export function RestParameterTable({ slug, numPreviews, parameters, bodyParamete
<>
|
- {t('rest.reference.body')}
+ {t('body')}
|
- |
- {`${t('rest.reference.name')}, ${t('rest.reference.type')}, ${t(
- 'rest.reference.description'
- )}`}
- |
+ {`${t('name')}, ${t('type')}, ${t('description')}`} |
{bodyParameters.map((param, index) => (
diff --git a/components/parameter-table/types.ts b/components/parameter-table/types.ts
new file mode 100644
index 0000000000..460ba41ee7
--- /dev/null
+++ b/components/parameter-table/types.ts
@@ -0,0 +1,32 @@
+export interface Parameter {
+ in: string
+ name: string
+ description: string
+ required: boolean
+ schema: {
+ type: string
+ default?: string
+ enum?: Array
+ }
+}
+
+export interface BodyParameter {
+ in: string
+ name: string
+ description: string
+ type: string
+ isRequired?: boolean
+ default?: string
+ enum?: Array
+ childParamsGroups?: Array
+}
+
+export interface ChildParameter {
+ name: string
+ description: string
+ type: string
+ isRequired?: boolean
+ enum?: Array
+ default?: string
+ childParamsGroups?: ChildParameter[]
+}
diff --git a/components/rest/ParameterRow.tsx b/components/rest/ParameterRow.tsx
deleted file mode 100644
index b89332f5db..0000000000
--- a/components/rest/ParameterRow.tsx
+++ /dev/null
@@ -1,75 +0,0 @@
-import { useTranslation } from 'components/hooks/useTranslation'
-import { ChildBodyParametersRows } from './ChildBodyParametersRows'
-import type { ChildParameter } from './types'
-
-type Props = {
- rowParams: ChildParameter
- slug: string
- numPreviews?: number
- isChild?: boolean
-}
-
-export function ParameterRow({ rowParams, slug, numPreviews = 0, isChild = false }: Props) {
- const { t } = useTranslation('products')
- return (
- <>
-
- |
-
- {rowParams.name}
- {rowParams.type}
- {rowParams.isRequired ? (
-
- {t('rest.reference.required')}
-
- ) : null}
-
-
-
- |
-
- {rowParams.childParamsGroups && rowParams.childParamsGroups.length > 0 && (
-
- )}
- >
- )
-}
diff --git a/components/rest/RestOperation.tsx b/components/rest/RestOperation.tsx
index 19b8a8246f..e96e04ea19 100644
--- a/components/rest/RestOperation.tsx
+++ b/components/rest/RestOperation.tsx
@@ -8,7 +8,7 @@ import { Link } from 'components/Link'
import { useTranslation } from 'components/hooks/useTranslation'
import { RestPreviewNotice } from './RestPreviewNotice'
import styles from './RestOperation.module.scss'
-import { RestParameterTable } from './RestParameterTable'
+import { ParameterTable } from 'components/parameter-table/ParameterTable'
import { RestCodeSamples } from './RestCodeSamples'
import { RestStatusCodes } from './RestStatusCodes'
import { Operation } from './types'
@@ -17,11 +17,20 @@ type Props = {
operation: Operation
}
+// all REST operations have this accept header by default
+const DEFAULT_ACCEPT_HEADER = {
+ name: 'accept',
+ type: 'string',
+ description: `Setting to application/vnd.github+json is recommended. `,
+ isRequired: false,
+}
+
export function RestOperation({ operation }: Props) {
const slug = slugger.slug(operation.title)
const { t } = useTranslation('products')
const router = useRouter()
+ const headers = [DEFAULT_ACCEPT_HEADER]
const numPreviews = operation.previews.length
const hasStatusCodes = operation.statusCodes.length > 0
const hasCodeSamples = operation.codeExamples.length > 0
@@ -54,9 +63,11 @@ export function RestOperation({ operation }: Props) {
/>
{hasParameters && (
-
diff --git a/data/ui.yml b/data/ui.yml
index bc42b1be1f..b9905e5985 100644
--- a/data/ui.yml
+++ b/data/ui.yml
@@ -87,6 +87,19 @@ contribution_cta:
button: Make a contribution
or: Or,
to_guidelines: learn how to contribute.
+parameter_table:
+ body: Body parameters
+ default: Default
+ description: Description
+ enum_description_title: Can be one of
+ headers: Headers
+ name: Name
+ path: Path parameters
+ query: Query parameters
+ required: Required
+ see_preview_notice: See preview notice
+ see_preview_notices: See preview notices
+ type: Type
products:
graphql:
reference:
@@ -111,10 +124,7 @@ products:
updates: Updates
rest:
reference:
- default: Default
- name: Name
in: In
- type: Type
description: Description
notes: Notes
parameters: Parameters
@@ -126,18 +136,10 @@ products:
code_samples: Code samples
preview_notice: Preview notice
preview_notices: Preview notices
- see_preview_notice: See preview notice
- see_preview_notices: See preview notices
preview_header_is_required: This header is required
preview_notice_to_change: This API is under preview and subject to change
works_with: Works with
api_reference: REST API reference
- enum_description_title: Can be one of
- required: Required
- headers: Headers
- query: Query parameters
- path: Path parameters
- body: Body parameters
footer:
all_rights_reserved: All rights reserved
terms: Terms
|