diff --git a/api-specs/api/package.json b/api-specs/api/package.json index 5100a56087..0c1576dcc4 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" }, "dependencies": { - "@commercetools-docs/rmf-codegen": "13.13.0" + "@commercetools-docs/rmf-codegen": "13.25.0" } } diff --git a/api-specs/test/api.raml b/api-specs/test/api.raml index a540dcd3c2..de37b17e9b 100644 --- a/api-specs/test/api.raml +++ b/api-specs/test/api.raml @@ -475,6 +475,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: + Frontastic-Locale: + displayName: Frontastic Locale + type: string + description: Locale + Frontastic-Path: + displayName: Frontastic Path + type: string + description: Path + required: true + pattern: ^/.*$ + Accept: + displayName: Accept Header + type: string + description: Accept application/json Header + required: true + pattern: application/json + default: application/json + 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 # /resourceWithHeaders: # description: Tests use of specific headers. diff --git a/api-specs/test/package.json b/api-specs/test/package.json index 018dc4d2db..536c8a89d7 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" }, "dependencies": { - "@commercetools-docs/rmf-codegen": "13.13.0" + "@commercetools-docs/rmf-codegen": "13.25.0" } } diff --git a/packages/gatsby-theme-api-docs/package.json b/packages/gatsby-theme-api-docs/package.json index d2dfcc9fc8..4d1e2b9441 100644 --- a/packages/gatsby-theme-api-docs/package.json +++ b/packages/gatsby-theme-api-docs/package.json @@ -34,7 +34,7 @@ "unist-util-visit": "2.0.3" }, "devDependencies": { - "@commercetools-docs/rmf-codegen": "13.13.0", + "@commercetools-docs/rmf-codegen": "13.25.0", "gatsby": "4.24.4", "react": "18.2.0", "react-dom": "18.2.0" diff --git a/packages/gatsby-theme-api-docs/src/components/info.js b/packages/gatsby-theme-api-docs/src/components/info.js index 331e570f70..1dd312ac43 100644 --- a/packages/gatsby-theme-api-docs/src/components/info.js +++ b/packages/gatsby-theme-api-docs/src/components/info.js @@ -1,7 +1,17 @@ +import React from 'react'; +import PropTypes from 'prop-types'; import styled from '@emotion/styled'; +import { css } from '@emotion/react'; +import { Markdown, useISO310NumberFormatter } from '@commercetools-docs/ui-kit'; import { colors, dimensions, typography } from '../design-system'; -const Info = styled.span` +const customCodeStyle = css` + border: none; + background-color: unset; + padding: 0; +`; + +export const Info = styled.span` display: inline-block; border: 1px solid ${colors.light.borderInfo}; background-color: ${colors.light.surfaceInfo}; @@ -9,4 +19,40 @@ const Info = styled.span` font-size: ${typography.fontSizes.small}; `; -export default Info; +export const InfoValue = (props) => { + const value = props.children; + const valueType = typeof value; + const formatNumber = useISO310NumberFormatter(); + + switch (valueType) { + case 'boolean': + return value ? ( + '' + ) : ( + <> + : No + + ); + case 'number': + return ( + <> + :{' '} + + {formatNumber(value)} + + + ); + default: + return ( + <> + :{' '} + + {value} + + + ); + } +}; +InfoValue.propTypes = { + children: PropTypes.any.isRequired, +}; 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..e76188b4ac --- /dev/null +++ b/packages/gatsby-theme-api-docs/src/components/resource/method/headers.js @@ -0,0 +1,103 @@ +import React from 'react'; +import PropTypes from 'prop-types'; +import styled from '@emotion/styled'; +import SpacingsStack from '@commercetools-uikit/spacings-stack'; +import SpacingsInline from '@commercetools-uikit/spacings-inline'; +import { + Markdown, + designSystem, + markdownFragmentToReact, +} from '@commercetools-docs/ui-kit'; +import { Link as GatsbyLink } from '@commercetools-docs/gatsby-theme-docs'; +import transformURNLinksPlugin from '../../../utils/transform-urn-links-plugin'; +import capitalizeFirst from '../../../utils/capitalize-first'; +import { typography } from '../../../design-system'; +import { Info, InfoValue } from '../../info'; +import Required from '../../required'; +import Table from '../../table'; +import Title from './title'; + +const PropertyName = styled.div` + white-space: nowrap; + line-height: ${typography.lineHeights.propertyType}; +`; +const PropertyType = styled.div` + line-height: ${typography.lineHeights.propertyType}; + color: ${designSystem.colors.light.textFaded}; +`; + +const DescriptionTextContainer = styled.span` + display: inline-block; +`; + +const Headers = (props) => { + console.log(props.headers); + return ( + + {props.title && {props.title}:} + + + {props.headers.map((header, headerIndex) => { + return ( + + + + + ); + })} + +
+ + + + + {header.displayName + ? header.displayName + : header.header} + + {'\u200B' /* zero-width space for the search crawler */} + {header.required && } + + + + {capitalizeFirst(header.type)} + {'\u200B' /* zero-width space for the search crawler */} + + + + + + {markdownFragmentToReact( + header.description, + { a: GatsbyLink }, + transformURNLinksPlugin + )} + + + {header.pattern && ( + + Pattern{header.pattern} + + )} + + +
+ + ); +}; + +Headers.propTypes = { + title: PropTypes.string.isRequired, + headers: PropTypes.arrayOf( + PropTypes.shape({ + header: PropTypes.string.isRequired, + displayName: PropTypes.string, + description: PropTypes.string, + type: PropTypes.string, + required: PropTypes.bool, + pattern: PropTypes.string, + }) + ).isRequired, +}; + +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 138c9e96af..b14e6925e0 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 @@ -13,6 +13,7 @@ import Url from './url'; import Scopes from './scopes'; import Responses from './responses'; import Parameters from './parameters'; +import Headers from './headers'; import QueryParameters from './query-parameters'; import RequestRepresentation from './request-representation'; import { DescriptionParagraph } from '../../description'; @@ -121,6 +122,10 @@ const Method = ({ )} + {method.headers && ( + + )} + {allUriParameters.length > 0 && ( diff --git a/packages/gatsby-theme-api-docs/src/components/resource/method/responses.js b/packages/gatsby-theme-api-docs/src/components/resource/method/responses.js index 5287cae230..691aecbe4a 100644 --- a/packages/gatsby-theme-api-docs/src/components/resource/method/responses.js +++ b/packages/gatsby-theme-api-docs/src/components/resource/method/responses.js @@ -52,7 +52,7 @@ const Responses = ({ apiKey, responses, contentType }) => { typeLocations, response.description )} - {contentType.length > 0 && ( + {contentType.length > 0 && !response.description && ( <> as {contentType} diff --git a/packages/gatsby-theme-api-docs/src/components/type/properties/rows/description.js b/packages/gatsby-theme-api-docs/src/components/type/properties/rows/description.js index ed3120cde1..a428fc3626 100644 --- a/packages/gatsby-theme-api-docs/src/components/type/properties/rows/description.js +++ b/packages/gatsby-theme-api-docs/src/components/type/properties/rows/description.js @@ -1,14 +1,14 @@ import React from 'react'; import PropTypes from 'prop-types'; import { css } from '@emotion/react'; -import { Markdown, useISO310NumberFormatter } from '@commercetools-docs/ui-kit'; +import { Markdown } from '@commercetools-docs/ui-kit'; import SpacingsInline from '@commercetools-uikit/spacings-inline'; import SpacingsStack from '@commercetools-uikit/spacings-stack'; import extractAdditionalInfo from '../../../../utils/extract-additional-info'; import capitalizeFirst from '../../../../utils/capitalize-first'; import { useApiTypeByApiKeyAndDisplayName } from '../../../../hooks/use-api-types'; import { DescriptionText } from '../../../description'; -import Info from '../../../info'; +import { Info, InfoValue } from '../../../info'; const customCodeStyle = css` border: none; @@ -60,43 +60,6 @@ ConstantLikeEnumDescription.propTypes = { }), }; -const InfoValue = (props) => { - const value = props.children; - const valueType = typeof value; - const formatNumber = useISO310NumberFormatter(); - - switch (valueType) { - case 'boolean': - return value ? ( - '' - ) : ( - <> - : No - - ); - case 'number': - return ( - <> - :{' '} - - {formatNumber(value)} - - - ); - default: - return ( - <> - :{' '} - - {value} - - - ); - } -}; -InfoValue.propTypes = { - children: PropTypes.any.isRequired, -}; const AdditionalInfo = (props) => { const additionalInfos = extractAdditionalInfo(props.property); return ( diff --git a/packages/gatsby-theme-api-docs/src/hooks/use-api-resources.js b/packages/gatsby-theme-api-docs/src/hooks/use-api-resources.js index 24156b4ec7..85ac840be7 100644 --- a/packages/gatsby-theme-api-docs/src/hooks/use-api-resources.js +++ b/packages/gatsby-theme-api-docs/src/hooks/use-api-resources.js @@ -25,6 +25,16 @@ export const useApiResources = () => { 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.js b/packages/gatsby-transformer-raml/src/schema/define-raml-resource.js index 28677c9d82..e1e0aebcb5 100644 --- a/packages/gatsby-transformer-raml/src/schema/define-raml-resource.js +++ b/packages/gatsby-transformer-raml/src/schema/define-raml-resource.js @@ -7,6 +7,7 @@ const defineRamlResource = ({ schema, createTypes }) => { description: String queryParameters: [RamlResourceQueryParameter!] responses: [RamlResourceResponse!] + headers: [RamlResourceHeaders!] codeExamples: [RamlResourceCodeExample!] } `, @@ -51,6 +52,7 @@ const defineRamlResource = ({ schema, createTypes }) => { queryParameters: '[RamlResourceQueryParameter!]', body: 'RamlResourceMethodBody', responses: '[RamlResourceResponse!]', + headers: '[RamlResourceHeaders!]', codeExamples: '[RamlResourceCodeExample!]', }, interfaces: ['Method'], @@ -64,6 +66,7 @@ const defineRamlResource = ({ schema, createTypes }) => { description: 'String', queryParameters: '[RamlResourceQueryParameter!]', responses: '[RamlResourceResponse!]', + headers: '[RamlResourceHeaders!]', codeExamples: '[RamlResourceCodeExample!]', }, interfaces: ['Method'], @@ -113,6 +116,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: 'RamlResourceMethodBody', fields: { diff --git a/packages/gatsby-transformer-raml/src/utils/resource/headers-to-array.js b/packages/gatsby-transformer-raml/src/utils/resource/headers-to-array.js new file mode 100644 index 0000000000..24cefa6433 --- /dev/null +++ b/packages/gatsby-transformer-raml/src/utils/resource/headers-to-array.js @@ -0,0 +1,11 @@ +function headersToArray(headers) { + if (headers) { + return Object.entries(headers).map(([key, value]) => { + return { header: key, ...value }; + }); + } + + return undefined; +} + +module.exports = headersToArray; diff --git a/packages/gatsby-transformer-raml/src/utils/resource/process-methods.js b/packages/gatsby-transformer-raml/src/utils/resource/process-methods.js index a44b05b756..1cc7f3a1d9 100644 --- a/packages/gatsby-transformer-raml/src/utils/resource/process-methods.js +++ b/packages/gatsby-transformer-raml/src/utils/resource/process-methods.js @@ -1,5 +1,6 @@ const parametersToArray = require('../parameters-to-array'); const responsesToArray = require('./responses-to-array'); +const headersToArray = require('./headers-to-array'); const codeExamplesToArray = require('./code-examples-to-array'); const examplesToArray = require('./examples-to-array').examplesToArray; const resolveExampleFile = require('./examples-to-array').resolveExampleFile; @@ -33,6 +34,10 @@ function processMethods({ returnedMethods[method].responses ); + returnedMethods[method].headers = headersToArray( + returnedMethods[method].headers + ); + returnedMethods[method].codeExamples = codeExamplesToArray( returnedMethods[method].codeExamples ); diff --git a/websites/api-docs-smoke-test/package.json b/websites/api-docs-smoke-test/package.json index 1a1638c5fc..cd941b23b9 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": "21.0.0", "@commercetools-docs/gatsby-theme-docs": "21.0.0", - "@commercetools-docs/rmf-codegen": "13.13.0", + "@commercetools-docs/rmf-codegen": "13.25.0", "gatsby": "4.24.4", "gatsby-cli": "4.24.0", "gatsby-source-filesystem": "4.24.0", 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 d00473a307..560742e7ea 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 @@ -28,3 +28,7 @@ import { ApiEndpointsForResource } from "/shortcodes" # /{projectKey}/resource/namespace-action-with-example + +# /\{projectKey}/resource/namespace-action-with-headers + + diff --git a/yarn.lock b/yarn.lock index c71847d41a..21b493fd3e 100644 --- a/yarn.lock +++ b/yarn.lock @@ -2171,7 +2171,7 @@ __metadata: version: 0.0.0-use.local resolution: "@commercetools-api-specs/api@workspace:api-specs/api" dependencies: - "@commercetools-docs/rmf-codegen": 13.13.0 + "@commercetools-docs/rmf-codegen": 13.25.0 languageName: unknown linkType: soft @@ -2179,7 +2179,7 @@ __metadata: version: 0.0.0-use.local resolution: "@commercetools-api-specs/test@workspace:api-specs/test" dependencies: - "@commercetools-docs/rmf-codegen": 13.13.0 + "@commercetools-docs/rmf-codegen": 13.25.0 languageName: unknown linkType: soft @@ -2189,7 +2189,7 @@ __metadata: dependencies: "@commercetools-docs/gatsby-transformer-mdx-introspection": 16.0.0 "@commercetools-docs/gatsby-transformer-raml": 13.3.0 - "@commercetools-docs/rmf-codegen": 13.13.0 + "@commercetools-docs/rmf-codegen": 13.25.0 "@commercetools-docs/ui-kit": 21.0.0 "@commercetools-uikit/design-system": 15.3.0 "@commercetools-uikit/spacings-inline": 15.3.0 @@ -2408,9 +2408,9 @@ __metadata: languageName: unknown linkType: soft -"@commercetools-docs/rmf-codegen@npm:13.13.0": - version: 13.13.0 - resolution: "@commercetools-docs/rmf-codegen@npm:13.13.0" +"@commercetools-docs/rmf-codegen@npm:13.25.0": + version: 13.25.0 + resolution: "@commercetools-docs/rmf-codegen@npm:13.25.0" dependencies: globby: ^13.1.1 js-yaml: ^4.0.0 @@ -2419,7 +2419,7 @@ __metadata: bin: raml-markdownlint: bin/raml-markdownlint.mjs rmf-codegen: bin/rmf-codegen.js - checksum: 3776682cd6eb06e4709b2eafafc1582d03157e8c053f5de5e47bdc68104fefbaeeb3049d2af78a66be164a5eb89b0299a1c41572783bf1aab517f9482899f9cf + checksum: aca0a8ca82afd886ab9a976959768598151a43a9403bffb7600a7e7e0169aaf91de9bd166c4d9bfc4793718165a924c2f20f90492c5d4fec5a8488703476ab34 languageName: node linkType: hard @@ -3054,7 +3054,7 @@ __metadata: dependencies: "@commercetools-docs/gatsby-theme-api-docs": 21.0.0 "@commercetools-docs/gatsby-theme-docs": 21.0.0 - "@commercetools-docs/rmf-codegen": 13.13.0 + "@commercetools-docs/rmf-codegen": 13.25.0 gatsby: 4.24.4 gatsby-cli: 4.24.0 gatsby-source-filesystem: 4.24.0