diff --git a/.changeset/tame-falcons-hear.md b/.changeset/tame-falcons-hear.md new file mode 100644 index 0000000000..ad7c63fb5c --- /dev/null +++ b/.changeset/tame-falcons-hear.md @@ -0,0 +1,6 @@ +--- +'@commercetools-docs/gatsby-transformer-raml': patch +'@commercetools-docs/gatsby-theme-api-docs': patch +--- + +Request headers are now being displayed in the endpoints. diff --git a/api-specs/api/package.json b/api-specs/api/package.json index 8cc56d1bd8..c7dcb47b50 100644 --- a/api-specs/api/package.json +++ b/api-specs/api/package.json @@ -8,6 +8,6 @@ "generate-ramldoc:watch": "npx rmf-codegen generate ./api.raml -w -o ../../websites/api-docs-smoke-test/src/api-specs/api -t RAML_DOC --inline-examples" }, "dependencies": { - "@commercetools-docs/rmf-codegen": "13.30.0" + "@commercetools-docs/rmf-codegen": "13.34.0" } } diff --git a/api-specs/test/api.raml b/api-specs/test/api.raml index 7e16ad680a..5bfaaac24d 100644 --- a/api-specs/test/api.raml +++ b/api-specs/test/api.raml @@ -485,6 +485,43 @@ uses: type: object example: !include examples/action-success.json + /namespace-action-with-headers: + uriParameters: + namespace: + displayName: Namespace + type: string + description: The namespace where the action to invoked is located. + action: + displayName: Action + type: string + description: The name of the action to invoked. + get: + headers: + Accept: + displayName: Accept Header + type: string + description: Accept application/json Header. + required: true + pattern: application/json + default: application/json + Test-Header: + displayName: Header with special type. + type: objects.ObjectTestType + description: A header with a special type. + Path-Header: + displayName: Path Header + type: string + required: true + pattern: ^/.*$ + description: Use the GET method to allow the frontend to fetch data from a backend system. For the response, we recommend to use standard HTTP codes and `application/json` encoded content. The response will be structured as defined by the body property of the action. + responses: + 200: + description: The response will be structured as defined by the body property of the action. + body: + application/json: + type: object + example: !include examples/action-success.json + /json-serializable-primitive-type: put: description: Use the PUT method to write data to a backend system. Any JSON serializable payload is accepted. The following request example adds a product to a cart. For the response, we recommend to use standard HTTP codes and `application/json` encoded content. The response will be structured [as defined by the `body` property of the action](/). The following response example contains the updated cart information, which includes the added product. diff --git a/api-specs/test/package.json b/api-specs/test/package.json index c3ead67d25..c8bb8ced52 100644 --- a/api-specs/test/package.json +++ b/api-specs/test/package.json @@ -8,6 +8,6 @@ "generate-ramldoc:watch": "npx rmf-codegen generate ./api.raml -w -o ../../websites/api-docs-smoke-test/src/api-specs/test -t RAML_DOC --inline-examples" }, "dependencies": { - "@commercetools-docs/rmf-codegen": "13.30.0" + "@commercetools-docs/rmf-codegen": "13.34.0" } } diff --git a/packages/gatsby-theme-api-docs/package.json b/packages/gatsby-theme-api-docs/package.json index 1822310808..fca129a60e 100644 --- a/packages/gatsby-theme-api-docs/package.json +++ b/packages/gatsby-theme-api-docs/package.json @@ -34,7 +34,7 @@ "unist-util-visit": "5.0.0" }, "devDependencies": { - "@commercetools-docs/rmf-codegen": "13.30.0", + "@commercetools-docs/rmf-codegen": "13.34.0", "gatsby": "5.12.12", "react": "18.2.0", "react-dom": "18.2.0" diff --git a/packages/gatsby-theme-api-docs/src/components/resource/method/headers.js b/packages/gatsby-theme-api-docs/src/components/resource/method/headers.js new file mode 100644 index 0000000000..3626c356ee --- /dev/null +++ b/packages/gatsby-theme-api-docs/src/components/resource/method/headers.js @@ -0,0 +1,131 @@ +import React from 'react'; +import PropTypes from 'prop-types'; +import styled from '@emotion/styled'; +import { + Markdown, + designSystem as uiKitDesignSystem, +} from '@commercetools-docs/ui-kit'; +import SpacingsStack from '@commercetools-uikit/spacings-stack'; +import SpacingsInline from '@commercetools-uikit/spacings-inline'; +import useTypesToRender from '../../../hooks/use-type-to-render'; +import Required from '../../required'; +import Table from '../../table'; +import Title from './title'; +import { DescriptionText } from '../../description'; +import Info from '../../info'; +import { typography } from '../../../design-system'; + +// inline-blocks inside a block are wrapped first before wrapping inline. +// this implements a wrapping behavior where property name and type are separated +// into lines before the name is wrapped in itself if it consists of multiple words. +const HeaderName = styled.div` + display: inline-block; + margin-right: ${uiKitDesignSystem.dimensions.spacings.s}; + white-space: nowrap; + line-height: ${typography.lineHeights.propertyType}; +`; +const HeaderType = styled.div` + display: inline-block; + line-height: ${typography.lineHeights.propertyType}; + color: ${uiKitDesignSystem.colors.light.textFaded}; +`; + +const Pattern = styled.code` + color: ${uiKitDesignSystem.colors.light.textHighlight}; + letter-spacing: 0.03em; +`; + +const Headers = (props) => { + return ( + + {props.title && {props.title}:} + + + {props.headers.map((header) => { + return ( + + ); + })} + +
+ + ); +}; +Headers.propTypes = { + apiKey: PropTypes.string, + title: PropTypes.string, + headers: PropTypes.arrayOf( + PropTypes.shape({ + displayName: PropTypes.string.isRequired, + header: PropTypes.string.isRequired, + type: PropTypes.string.isRequired, + description: PropTypes.string, + required: PropTypes.bool, + pattern: PropTypes.string, + enum: PropTypes.string, + }).isRequired + ).isRequired, +}; +Headers.displayName = 'Headers'; + +function HeaderRow(props) { + const typesToRender = useTypesToRender({ + property: props.header, + apiKey: props.apiKey, + isParameter: false, + }); + const typeToRender = typesToRender[0]; // safe as we expect a single item in the array + + return ( + + + + + {props.header.header} + {props.header.required && } + + + {'\u200B' /* zero-width space for the search crawler */} + + {typeToRender.displayPrefix && typeToRender.displayPrefix} + + {typeToRender.type} + + {'\u200B' /* zero-width space for the search crawler */} + + + + {props.header.description && ( + + )} + {props.header.pattern && ( +
+ + Pattern: {props.header.pattern} + +
+ )} + + + + ); +} +HeaderRow.propTypes = { + apiKey: PropTypes.string, + header: PropTypes.shape({ + displayName: PropTypes.string.isRequired, + header: PropTypes.string.isRequired, + type: PropTypes.string.isRequired, + description: PropTypes.string, + required: PropTypes.bool, + pattern: PropTypes.string, + enum: PropTypes.string, + }).isRequired, +}; +HeaderRow.displayName = 'HeaderRow'; + +export default Headers; diff --git a/packages/gatsby-theme-api-docs/src/components/resource/method/method.js b/packages/gatsby-theme-api-docs/src/components/resource/method/method.js index a1b32957f6..86ed7dfe3b 100644 --- a/packages/gatsby-theme-api-docs/src/components/resource/method/method.js +++ b/packages/gatsby-theme-api-docs/src/components/resource/method/method.js @@ -11,6 +11,7 @@ import { generateEndpointURN } from '../../../utils/ctp-urn'; import { tokens, dimensions, colors, typography } from '../../../design-system'; import Url from './url'; import Scopes from './scopes'; +import Headers from './headers'; import Responses from './responses'; import Parameters from './parameters'; import QueryParameters from './query-parameters'; @@ -154,6 +155,14 @@ const Method = ({ /> )} + {method.headers && ( + + )} + {method.body && ( { type } } + headers { + header + displayName + default + enum + description + type + required + pattern + } responses { code description diff --git a/packages/gatsby-transformer-raml/src/schema/define-raml-resource.mjs b/packages/gatsby-transformer-raml/src/schema/define-raml-resource.mjs index a00805f57c..2a2ba4bb15 100644 --- a/packages/gatsby-transformer-raml/src/schema/define-raml-resource.mjs +++ b/packages/gatsby-transformer-raml/src/schema/define-raml-resource.mjs @@ -6,6 +6,7 @@ const defineRamlResource = ({ schema, createTypes }) => { displayName: String description: String queryParameters: [RamlResourceQueryParameter!] + headers: [RamlResourceHeaders!] responses: [RamlResourceResponse!] codeExamples: [RamlResourceCodeExample!] } @@ -49,6 +50,7 @@ const defineRamlResource = ({ schema, createTypes }) => { displayName: 'String', description: 'String', queryParameters: '[RamlResourceQueryParameter!]', + headers: '[RamlResourceHeaders!]', body: 'RamlResourceMethodBody', responses: '[RamlResourceResponse!]', codeExamples: '[RamlResourceCodeExample!]', @@ -63,6 +65,7 @@ const defineRamlResource = ({ schema, createTypes }) => { displayName: 'String', description: 'String', queryParameters: '[RamlResourceQueryParameter!]', + headers: '[RamlResourceHeaders!]', responses: '[RamlResourceResponse!]', codeExamples: '[RamlResourceCodeExample!]', }, @@ -96,6 +99,21 @@ const defineRamlResource = ({ schema, createTypes }) => { }, }), + schema.buildObjectType({ + name: 'RamlResourceHeaders', + fields: { + header: 'String!', + displayName: 'String', + default: 'String', + pattern: 'String', + type: 'String', + builtinType: 'String', + description: 'String', + required: 'Boolean', + enum: '[String!]', + }, + }), + schema.buildObjectType({ name: 'RamlResourceQueryUnionParameter', fields: { diff --git a/packages/gatsby-transformer-raml/src/utils/resource/headers-to-array.mjs b/packages/gatsby-transformer-raml/src/utils/resource/headers-to-array.mjs new file mode 100644 index 0000000000..a6d0c0d15e --- /dev/null +++ b/packages/gatsby-transformer-raml/src/utils/resource/headers-to-array.mjs @@ -0,0 +1,11 @@ +function headersToArray(headers) { + if (headers) { + return Object.entries(headers).map(([key, value]) => { + return { header: key, ...value }; + }); + } + + return undefined; +} + +export default headersToArray; diff --git a/packages/gatsby-transformer-raml/src/utils/resource/process-methods.mjs b/packages/gatsby-transformer-raml/src/utils/resource/process-methods.mjs index 08afd79859..37249b8e3c 100644 --- a/packages/gatsby-transformer-raml/src/utils/resource/process-methods.mjs +++ b/packages/gatsby-transformer-raml/src/utils/resource/process-methods.mjs @@ -1,5 +1,6 @@ import parametersToArray from '../parameters-to-array.mjs'; import responsesToArray from './responses-to-array.mjs'; +import headersToArray from './headers-to-array.mjs'; import codeExamplesToArray from './code-examples-to-array.mjs'; import { examplesToArray } from './examples-to-array.mjs'; import sortProperties from '../sort-properties.mjs'; @@ -28,6 +29,10 @@ function processMethods({ }) : returnedMethods[method].queryParameters; + returnedMethods[method].headers = headersToArray( + returnedMethods[method].headers + ); + returnedMethods[method].responses = responsesToArray( returnedMethods[method].responses ); diff --git a/websites/api-docs-smoke-test/package.json b/websites/api-docs-smoke-test/package.json index 1520ea4f13..3e942098a3 100644 --- a/websites/api-docs-smoke-test/package.json +++ b/websites/api-docs-smoke-test/package.json @@ -20,7 +20,7 @@ "dependencies": { "@commercetools-docs/gatsby-theme-api-docs": "24.0.3", "@commercetools-docs/gatsby-theme-docs": "24.1.0", - "@commercetools-docs/rmf-codegen": "13.30.0", + "@commercetools-docs/rmf-codegen": "13.34.0", "gatsby": "5.12.12", "gatsby-cli": "5.12.4", "gatsby-source-filesystem": "5.12.1", diff --git a/websites/api-docs-smoke-test/src/content/endpoints/endpoints-for-resource.mdx b/websites/api-docs-smoke-test/src/content/endpoints/endpoints-for-resource.mdx index 76a3052782..b86e46192b 100644 --- a/websites/api-docs-smoke-test/src/content/endpoints/endpoints-for-resource.mdx +++ b/websites/api-docs-smoke-test/src/content/endpoints/endpoints-for-resource.mdx @@ -29,6 +29,10 @@ import { ApiEndpointsForResource } from "/shortcodes" +# /{projectKey}/resource/namespace-action-with-headers + + + # /{projectKey}/resource/json-serializable-primitive-type diff --git a/yarn.lock b/yarn.lock index ea2b7f45af..83bc455040 100644 --- a/yarn.lock +++ b/yarn.lock @@ -3339,7 +3339,7 @@ __metadata: version: 0.0.0-use.local resolution: "@commercetools-api-specs/api@workspace:api-specs/api" dependencies: - "@commercetools-docs/rmf-codegen": 13.30.0 + "@commercetools-docs/rmf-codegen": 13.34.0 languageName: unknown linkType: soft @@ -3347,7 +3347,7 @@ __metadata: version: 0.0.0-use.local resolution: "@commercetools-api-specs/test@workspace:api-specs/test" dependencies: - "@commercetools-docs/rmf-codegen": 13.30.0 + "@commercetools-docs/rmf-codegen": 13.34.0 languageName: unknown linkType: soft @@ -3357,7 +3357,7 @@ __metadata: dependencies: "@commercetools-docs/gatsby-transformer-mdx-introspection": 16.0.0 "@commercetools-docs/gatsby-transformer-raml": 13.6.0 - "@commercetools-docs/rmf-codegen": 13.30.0 + "@commercetools-docs/rmf-codegen": 13.34.0 "@commercetools-docs/ui-kit": 24.0.3 "@commercetools-uikit/design-system": 18.4.0 "@commercetools-uikit/spacings-inline": 18.4.0 @@ -3548,9 +3548,9 @@ __metadata: languageName: unknown linkType: soft -"@commercetools-docs/rmf-codegen@npm:13.30.0": - version: 13.30.0 - resolution: "@commercetools-docs/rmf-codegen@npm:13.30.0" +"@commercetools-docs/rmf-codegen@npm:13.34.0": + version: 13.34.0 + resolution: "@commercetools-docs/rmf-codegen@npm:13.34.0" dependencies: globby: ^13.1.1 js-yaml: ^4.0.0 @@ -3559,7 +3559,7 @@ __metadata: bin: raml-markdownlint: bin/raml-markdownlint.mjs rmf-codegen: bin/rmf-codegen.js - checksum: cc34291fead78283ff9b37e16ea1f60bbb5390162884a47d412f4174813b295cf4579e4cdf5871eed6dac11e5e50ecedbea6f92ec8fd9427d67200a8e21626ac + checksum: 15f17d1577b1364c64855088e49c6c3911834a9bc972703f8f981787804ea134bb4a2d0857e884306c66fa22e559748ad4f4808a0f40d01707211d486896fc09 languageName: node linkType: hard @@ -4534,7 +4534,7 @@ __metadata: dependencies: "@commercetools-docs/gatsby-theme-api-docs": 24.0.3 "@commercetools-docs/gatsby-theme-docs": 24.1.0 - "@commercetools-docs/rmf-codegen": 13.30.0 + "@commercetools-docs/rmf-codegen": 13.34.0 gatsby: 5.12.12 gatsby-cli: 5.12.4 gatsby-source-filesystem: 5.12.1