From ac79c8ffd95f38586e25c8f4090edbb03e711270 Mon Sep 17 00:00:00 2001 From: Timon Turak Date: Mon, 6 Feb 2023 14:45:37 +0100 Subject: [PATCH 1/5] chore: update rmf-codegen + add examples --- api-specs/api/package.json | 2 +- api-specs/test/api.raml | 83 +++++++++++++++++++ api-specs/test/examples/action-error.json | 4 + api-specs/test/examples/action-payload.json | 6 ++ api-specs/test/package.json | 2 +- packages/gatsby-theme-api-docs/package.json | 2 +- websites/api-docs-smoke-test/package.json | 2 +- .../endpoints/endpoints-for-resource.mdx | 4 + yarn.lock | 16 ++-- 9 files changed, 109 insertions(+), 12 deletions(-) create mode 100644 api-specs/test/examples/action-error.json create mode 100644 api-specs/test/examples/action-payload.json 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..77566c1ffe 100644 --- a/api-specs/test/api.raml +++ b/api-specs/test/api.raml @@ -54,6 +54,31 @@ uses: soft-links: types/soft-links.raml unions: types/unions.raml +traits: + right-header: + headers: + Accept: + displayName: Accept Header + type: string + description: Accept application/json Header + required: true + pattern: ^application/json$ + default: application/json + frontastic-locale: + headers: + Frontastic-Locale: + displayName: Frontastic Locale + type: any + description: Locale + action-errorable: + responses: + 400: + description: Action not registered. + body: + application/json: + type: any + example: !include ./examples/action-error.json + # Endpoints ("Resources" in RAML and HTTP terminology) # Every CT API endpoint starts at this root /{projectKey}: @@ -475,6 +500,64 @@ 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. [Namespaces are used to categorize actions](/../frontend-development/developing-an-action-extension#1-implement-the-action). + action: + displayName: Action + type: string + description: The name of the action to invoked. + get: + is: + - action-errorable + - right-header + - frontastic-locale + 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](/../frontend-development/developing-an-action-extension#1-implement-the-action). The following response example contains information about a cart. + responses: + 200: + description: The response will be structured [as defined by the `body` property of the action](/../frontend-development/developing-an-action-extension#1-implement-the-action). We recommend to use standard HTTP response codes and `application/json` encoded content. The following response example contains information about a cart. + body: + application/json: + type: object + example: !include examples/action-success.json + post: + is: + - action-errorable + - right-header + - frontastic-locale + description: Use the POST 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](/../frontend-development/developing-an-action-extension#1-implement-the-action). The following response example contains the updated cart information, which includes the added product. + body: + application/json: + type: any + example: !include examples/action-payload.json + responses: + 200: + description: The response will be structured [as defined by the `body` property of the action](/../frontend-development/developing-an-action-extension#1-implement-the-action). We recommend to use standard HTTP response codes and `application/json` encoded content. The following response example contains information about a cart. + body: + application/json: + type: object + example: !include examples/action-success.json + put: + is: + - action-errorable + - right-header + - frontastic-locale + 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](/../frontend-development/developing-an-action-extension#1-implement-the-action). The following response example contains the updated cart information, which includes the added product. + body: + application/json: + type: any + example: !include examples/action-payload.json + responses: + 200: + description: The response will be structured [as defined by the `body` property of the action](/../frontend-development/developing-an-action-extension#1-implement-the-action). We recommend to use standard HTTP response codes and `application/json` encoded content. The following response example contains information about a cart. + body: + application/json: + type: any + example: !include examples/action-success.json + # /resourceWithHeaders: # description: Tests use of specific headers. diff --git a/api-specs/test/examples/action-error.json b/api-specs/test/examples/action-error.json new file mode 100644 index 0000000000..0a608becd3 --- /dev/null +++ b/api-specs/test/examples/action-error.json @@ -0,0 +1,4 @@ +{ + "ok": false, + "message": "Action \"myAction\" in namespace \"myNamespace\" is not registered." +} diff --git a/api-specs/test/examples/action-payload.json b/api-specs/test/examples/action-payload.json new file mode 100644 index 0000000000..e9e1727f74 --- /dev/null +++ b/api-specs/test/examples/action-payload.json @@ -0,0 +1,6 @@ +{ + "variant": { + "sku": "M0E200KJ1200DSDJ", + "count": 1 + } +} 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/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 From d35ffd3aab3a6b514d8733898be69f5a2edad681 Mon Sep 17 00:00:00 2001 From: Timon Turak Date: Mon, 20 Feb 2023 09:12:14 +0100 Subject: [PATCH 2/5] feat: provide headers from the graphql schema --- api-specs/test/api.raml | 27 ++++--------------- .../components/resource/method/responses.js | 2 +- .../src/hooks/use-api-resources.js | 8 ++++++ .../src/schema/define-raml-resource.js | 15 +++++++++++ .../src/utils/resource/headers-to-array.js | 11 ++++++++ .../src/utils/resource/process-methods.js | 5 ++++ 6 files changed, 45 insertions(+), 23 deletions(-) create mode 100644 packages/gatsby-transformer-raml/src/utils/resource/headers-to-array.js diff --git a/api-specs/test/api.raml b/api-specs/test/api.raml index 77566c1ffe..bdbd4f5203 100644 --- a/api-specs/test/api.raml +++ b/api-specs/test/api.raml @@ -515,27 +515,10 @@ traits: - action-errorable - right-header - frontastic-locale - 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](/../frontend-development/developing-an-action-extension#1-implement-the-action). The following response example contains information about a cart. + 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](/../frontend-development/developing-an-action-extension#1-implement-the-action). The following response example contains information about a cart. responses: 200: - description: The response will be structured [as defined by the `body` property of the action](/../frontend-development/developing-an-action-extension#1-implement-the-action). We recommend to use standard HTTP response codes and `application/json` encoded content. The following response example contains information about a cart. - body: - application/json: - type: object - example: !include examples/action-success.json - post: - is: - - action-errorable - - right-header - - frontastic-locale - description: Use the POST 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](/../frontend-development/developing-an-action-extension#1-implement-the-action). The following response example contains the updated cart information, which includes the added product. - body: - application/json: - type: any - example: !include examples/action-payload.json - responses: - 200: - description: The response will be structured [as defined by the `body` property of the action](/../frontend-development/developing-an-action-extension#1-implement-the-action). We recommend to use standard HTTP response codes and `application/json` encoded content. The following response example contains information about a cart. + description: The response will be structured [as defined by the body property of the action](/../frontend-development/developing-an-action-extension#1-implement-the-action). We recommend to use standard HTTP response codes and `application/json` encoded content. The following response example contains information about a cart. body: application/json: type: object @@ -545,17 +528,17 @@ traits: - action-errorable - right-header - frontastic-locale - 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](/../frontend-development/developing-an-action-extension#1-implement-the-action). The following response example contains the updated cart information, which includes the added product. + 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](/../frontend-development/developing-an-action-extension#1-implement-the-action). The following response example contains the updated cart information, which includes the added product. body: application/json: type: any example: !include examples/action-payload.json responses: 200: - description: The response will be structured [as defined by the `body` property of the action](/../frontend-development/developing-an-action-extension#1-implement-the-action). We recommend to use standard HTTP response codes and `application/json` encoded content. The following response example contains information about a cart. + description: The response will be structured [as defined by the body property of the action](/../frontend-development/developing-an-action-extension#1-implement-the-action). We recommend to use standard HTTP response codes and `application/json` encoded content. The following response example contains information about a cart. body: application/json: - type: any + type: object example: !include examples/action-success.json 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/hooks/use-api-resources.js b/packages/gatsby-theme-api-docs/src/hooks/use-api-resources.js index 24156b4ec7..b046f1cc56 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,14 @@ export const useApiResources = () => { type } } + headers { + header + builtinType + 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..fcfd0b6fc0 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,18 @@ const defineRamlResource = ({ schema, createTypes }) => { }, }), + schema.buildObjectType({ + name: 'RamlResourceHeaders', + fields: { + header: 'String!', + pattern: 'String', + type: 'String', + builtinType: 'String', + description: 'String', + required: 'Boolean', + }, + }), + 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 ); From 60fb87de3483ce051082b2b918477fe027093ecf Mon Sep 17 00:00:00 2001 From: Timon Turak Date: Mon, 20 Feb 2023 10:19:49 +0100 Subject: [PATCH 3/5] feat: display headers --- api-specs/test/api.raml | 20 +------ api-specs/test/examples/action-payload.json | 6 -- .../src/components/resource/method/headers.js | 58 +++++++++++++++++++ .../src/components/resource/method/method.js | 3 + 4 files changed, 62 insertions(+), 25 deletions(-) delete mode 100644 api-specs/test/examples/action-payload.json create mode 100644 packages/gatsby-theme-api-docs/src/components/resource/method/headers.js diff --git a/api-specs/test/api.raml b/api-specs/test/api.raml index bdbd4f5203..b277b8eeee 100644 --- a/api-specs/test/api.raml +++ b/api-specs/test/api.raml @@ -62,7 +62,7 @@ traits: type: string description: Accept application/json Header required: true - pattern: ^application/json$ + pattern: application/json default: application/json frontastic-locale: headers: @@ -523,24 +523,6 @@ traits: application/json: type: object example: !include examples/action-success.json - put: - is: - - action-errorable - - right-header - - frontastic-locale - 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](/../frontend-development/developing-an-action-extension#1-implement-the-action). The following response example contains the updated cart information, which includes the added product. - body: - application/json: - type: any - example: !include examples/action-payload.json - responses: - 200: - description: The response will be structured [as defined by the body property of the action](/../frontend-development/developing-an-action-extension#1-implement-the-action). We recommend to use standard HTTP response codes and `application/json` encoded content. The following response example contains information about a cart. - body: - application/json: - type: object - example: !include examples/action-success.json - # /resourceWithHeaders: # description: Tests use of specific headers. diff --git a/api-specs/test/examples/action-payload.json b/api-specs/test/examples/action-payload.json deleted file mode 100644 index e9e1727f74..0000000000 --- a/api-specs/test/examples/action-payload.json +++ /dev/null @@ -1,6 +0,0 @@ -{ - "variant": { - "sku": "M0E200KJ1200DSDJ", - "count": 1 - } -} 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..561518a7b5 --- /dev/null +++ b/packages/gatsby-theme-api-docs/src/components/resource/method/headers.js @@ -0,0 +1,58 @@ +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 { + designSystem, + markdownFragmentToReact, +} from '@commercetools-docs/ui-kit'; + +const HeaderListContainer = styled.div` + padding: 0 ${designSystem.dimensions.spacings.l}; +`; + +const HeaderListItem = styled.li` + padding: ${designSystem.dimensions.spacings.xs} 0px; +`; + +const highlightHeader = (header) => `\`${header}\``; + +const Headers = (props) => { + return ( + +
Headers:
+ +
    + {props.headers.map((header, itemImdex) => { + console.log(header); + return ( + + + {markdownFragmentToReact(highlightHeader(header.header))} + {header.required &&

    -

    } + {header.required &&

    Required

    } +     +     + ); + })} +
+ + + ); +}; + +Headers.propTypes = { + headers: PropTypes.arrayOf( + PropTypes.shape({ + header: PropTypes.string.isRequired, + builtinType: 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..566517d0b1 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,8 @@ const Method = ({ )} + {method.headers && } + {allUriParameters.length > 0 && ( Date: Mon, 27 Feb 2023 10:11:51 +0100 Subject: [PATCH 4/5] refactor: enhance ui for headers --- api-specs/test/api.raml | 47 ++++------ .../src/components/info.js | 50 +++++++++- .../src/components/resource/method/headers.js | 93 +++++++++++++++---- .../src/components/resource/method/method.js | 4 +- .../components/resource/method/parameters.js | 2 +- .../type/properties/rows/description.js | 41 +------- .../src/hooks/use-api-resources.js | 4 +- .../src/schema/define-raml-resource.js | 3 + 8 files changed, 151 insertions(+), 93 deletions(-) diff --git a/api-specs/test/api.raml b/api-specs/test/api.raml index b277b8eeee..7835f0b259 100644 --- a/api-specs/test/api.raml +++ b/api-specs/test/api.raml @@ -54,31 +54,6 @@ uses: soft-links: types/soft-links.raml unions: types/unions.raml -traits: - right-header: - headers: - Accept: - displayName: Accept Header - type: string - description: Accept application/json Header - required: true - pattern: application/json - default: application/json - frontastic-locale: - headers: - Frontastic-Locale: - displayName: Frontastic Locale - type: any - description: Locale - action-errorable: - responses: - 400: - description: Action not registered. - body: - application/json: - type: any - example: !include ./examples/action-error.json - # Endpoints ("Resources" in RAML and HTTP terminology) # Every CT API endpoint starts at this root /{projectKey}: @@ -511,10 +486,24 @@ traits: type: string description: The name of the action to invoked. get: - is: - - action-errorable - - right-header - - frontastic-locale + 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](/../frontend-development/developing-an-action-extension#1-implement-the-action). The following response example contains information about a cart. responses: 200: 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 index 561518a7b5..064f9c028b 100644 --- a/packages/gatsby-theme-api-docs/src/components/resource/method/headers.js +++ b/packages/gatsby-theme-api-docs/src/components/resource/method/headers.js @@ -4,49 +4,102 @@ 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 RegexProperty from '../../type/properties/regex-properties'; +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 HeaderListContainer = styled.div` - padding: 0 ${designSystem.dimensions.spacings.l}; +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 HeaderListItem = styled.li` - padding: ${designSystem.dimensions.spacings.xs} 0px; +const DescriptionTextContainer = styled.span` + display: inline-block; `; -const highlightHeader = (header) => `\`${header}\``; +const isRegex = (string) => + string.charAt(0) === '/' && string.charAt(string.length - 1) === '/'; const Headers = (props) => { + console.log(props.headers); return ( -
Headers:
- -
    - {props.headers.map((header, itemImdex) => { - console.log(header); + {props.title && {props.title}:} + + + {props.headers.map((header, headerIndex) => { return ( - - - {markdownFragmentToReact(highlightHeader(header.header))} - {header.required &&

    -

    } - {header.required &&

    Required

    } -     -     + + + + ); })} - - + +
    + + + + {isRegex(header.header) ? ( + + ) : ( + + {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, - builtinType: PropTypes.string, + displayName: PropTypes.string, description: PropTypes.string, type: PropTypes.string, required: PropTypes.bool, 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 566517d0b1..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 @@ -122,7 +122,9 @@ const Method = ({ )} - {method.headers && } + {method.headers && ( + + )} {allUriParameters.length > 0 && ( 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 b046f1cc56..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 @@ -27,7 +27,9 @@ export const useApiResources = () => { } headers { header - builtinType + displayName + default + enum description type required 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 fcfd0b6fc0..e1e0aebcb5 100644 --- a/packages/gatsby-transformer-raml/src/schema/define-raml-resource.js +++ b/packages/gatsby-transformer-raml/src/schema/define-raml-resource.js @@ -120,11 +120,14 @@ const defineRamlResource = ({ schema, createTypes }) => { name: 'RamlResourceHeaders', fields: { header: 'String!', + displayName: 'String', + default: 'String', pattern: 'String', type: 'String', builtinType: 'String', description: 'String', required: 'Boolean', + enum: '[String!]', }, }), From 694d52c322697930b999169d36c5e266a939c28f Mon Sep 17 00:00:00 2001 From: Timon Turak Date: Mon, 27 Feb 2023 14:45:08 +0100 Subject: [PATCH 5/5] refactor: example + header component --- api-specs/test/api.raml | 6 +++--- api-specs/test/examples/action-error.json | 4 ---- .../src/components/resource/method/headers.js | 18 +++++------------- 3 files changed, 8 insertions(+), 20 deletions(-) delete mode 100644 api-specs/test/examples/action-error.json diff --git a/api-specs/test/api.raml b/api-specs/test/api.raml index 7835f0b259..de37b17e9b 100644 --- a/api-specs/test/api.raml +++ b/api-specs/test/api.raml @@ -480,7 +480,7 @@ uses: namespace: displayName: Namespace type: string - description: The namespace where the action to invoked is located. [Namespaces are used to categorize actions](/../frontend-development/developing-an-action-extension#1-implement-the-action). + description: The namespace where the action to invoked is located. action: displayName: Action type: string @@ -504,10 +504,10 @@ uses: 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](/../frontend-development/developing-an-action-extension#1-implement-the-action). The following response example contains information about a cart. + 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](/../frontend-development/developing-an-action-extension#1-implement-the-action). We recommend to use standard HTTP response codes and `application/json` encoded content. The following response example contains information about a cart. + description: The response will be structured as defined by the body property of the action. body: application/json: type: object diff --git a/api-specs/test/examples/action-error.json b/api-specs/test/examples/action-error.json deleted file mode 100644 index 0a608becd3..0000000000 --- a/api-specs/test/examples/action-error.json +++ /dev/null @@ -1,4 +0,0 @@ -{ - "ok": false, - "message": "Action \"myAction\" in namespace \"myNamespace\" is not registered." -} 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 index 064f9c028b..e76188b4ac 100644 --- a/packages/gatsby-theme-api-docs/src/components/resource/method/headers.js +++ b/packages/gatsby-theme-api-docs/src/components/resource/method/headers.js @@ -10,7 +10,6 @@ import { } from '@commercetools-docs/ui-kit'; import { Link as GatsbyLink } from '@commercetools-docs/gatsby-theme-docs'; import transformURNLinksPlugin from '../../../utils/transform-urn-links-plugin'; -import RegexProperty from '../../type/properties/regex-properties'; import capitalizeFirst from '../../../utils/capitalize-first'; import { typography } from '../../../design-system'; import { Info, InfoValue } from '../../info'; @@ -31,9 +30,6 @@ const DescriptionTextContainer = styled.span` display: inline-block; `; -const isRegex = (string) => - string.charAt(0) === '/' && string.charAt(string.length - 1) === '/'; - const Headers = (props) => { console.log(props.headers); return ( @@ -48,15 +44,11 @@ const Headers = (props) => { - {isRegex(header.header) ? ( - - ) : ( - - {header.displayName - ? header.displayName - : header.header} - - )} + + {header.displayName + ? header.displayName + : header.header} + {'\u200B' /* zero-width space for the search crawler */} {header.required && }