From d9ee6bc52c21a1e3d4c0937ee942e6b421bdc622 Mon Sep 17 00:00:00 2001 From: Timon Turak Date: Mon, 6 Feb 2023 14:45:37 +0100 Subject: [PATCH] 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 3c9f3eb036..b4f8849a4e 100644 --- a/packages/gatsby-theme-api-docs/package.json +++ b/packages/gatsby-theme-api-docs/package.json @@ -33,7 +33,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 9f14af277b..11f0c54ca4 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": "20.2.0", "@commercetools-docs/gatsby-theme-docs": "20.2.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 c933cc01b5..50300007a5 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 66ae0eaa37..2df82b3ddb 100644 --- a/yarn.lock +++ b/yarn.lock @@ -2083,7 +2083,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 @@ -2091,7 +2091,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 @@ -2100,7 +2100,7 @@ __metadata: resolution: "@commercetools-docs/gatsby-theme-api-docs@workspace:packages/gatsby-theme-api-docs" dependencies: "@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": 20.2.0 "@commercetools-uikit/design-system": 15.3.0 "@commercetools-uikit/spacings-inline": 15.3.0 @@ -2318,9 +2318,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 @@ -2329,7 +2329,7 @@ __metadata: bin: raml-markdownlint: bin/raml-markdownlint.mjs rmf-codegen: bin/rmf-codegen.js - checksum: 3776682cd6eb06e4709b2eafafc1582d03157e8c053f5de5e47bdc68104fefbaeeb3049d2af78a66be164a5eb89b0299a1c41572783bf1aab517f9482899f9cf + checksum: aca0a8ca82afd886ab9a976959768598151a43a9403bffb7600a7e7e0169aaf91de9bd166c4d9bfc4793718165a924c2f20f90492c5d4fec5a8488703476ab34 languageName: node linkType: hard @@ -2964,7 +2964,7 @@ __metadata: dependencies: "@commercetools-docs/gatsby-theme-api-docs": 20.2.0 "@commercetools-docs/gatsby-theme-docs": 20.2.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