From 545923ad33591f2f3e4c90b6f50f7783e952cac7 Mon Sep 17 00:00:00 2001 From: Marcin Slezak Date: Thu, 28 Sep 2023 14:13:57 +0200 Subject: [PATCH] update the contribution process and use OpenAPI from stoplight --- CONTRIBUTING.md | 10 ++-- reference/OpenAPI.json | 103 ++++++++++++++++++++--------------------- 2 files changed, 54 insertions(+), 59 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e2f6ecfb4..b542d9c16 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -114,13 +114,13 @@ Good practices: - Select the current public version in `Fork from` field, most likely `2018-08-01` - Type your version name in `Create version` field following the pattern: `2018-08-01-{your name}-{pull request number}` -- Make changes in the repository following patterns and good practices +- Make changes in the repository following patterns and good practices. - Deploy changes to test your documentation: - Update tables in markdown tables: - `npm run build-md-tables-from-openapi` - `npm run update-md-tables-in-doc` - - Deploy OpenAPI file by command `rdme openapi OpenAPI.json --id=<>`, where `<>` should be replaced by the OpenAPI ID that can be found on the `API Reference` page (looks screenshot) - - Deploy guides pages: `rdme docs ./docs/reference-docs --version=2018-08-01-{your name}-{pull request number}` + - Deploy OpenAPI file by command `rdme openapi ./reference/OpenAPI.json --id=<>`, where `<>` should be replaced by the OpenAPI ID that can be found on the `API Reference` page (looks screenshot) + - Deploy guides pages: `rdme docs ./docs/guides --version=2018-08-01-{your name}-{pull request number}` - Deploy api reference pages: `rdme docs ./docs/reference-docs --version=2018-08-01-{your name}-{pull request number}` - Fix docs order: `npm run readme-fix-docs-order -- --version=v2018-08-01-{your name}-{pull request number}` - test changes using preview on readme.io @@ -132,10 +132,6 @@ Good practices: - -![[Screenshot 2023-09-28 at 09.29.44.png]] - - ## How to merge PR and update public documentation > [!TODO] \ No newline at end of file diff --git a/reference/OpenAPI.json b/reference/OpenAPI.json index f5c191b84..457763af0 100644 --- a/reference/OpenAPI.json +++ b/reference/OpenAPI.json @@ -366,8 +366,7 @@ "in": "query", "required": false, "schema": { - "anyOf": [ - ] + "anyOf": [] }, "description": "A filter.", "style": "deepObject", @@ -38706,43 +38705,43 @@ } }, "22_filter_updated_at": { - "type": "object", - "title": "Updated at", - "properties": { - "updated_at": { - "$ref": "#/components/schemas/16_filter_conditions_date_time" - } - }, + "type": "object", + "title": "Updated at", + "properties": { + "updated_at": { + "$ref": "#/components/schemas/16_filter_conditions_date_time" + } + }, "description": "A filter on the list based on the object `updated_at` field. The value is a dictionary with the following options: `before`, `after`. A date value must be presented in ISO 8601 format (`2016-11-16T14:14:31Z` or `2016-11-16`). An example: `[updated_at][before]=2017-09-08T13:52:18.227Z`" }, "22_filter_created_at": { - "type": "object", - "title": "Created at", - "properties": { - "created_at": { - "$ref": "#/components/schemas/16_filter_conditions_date_time" - } - }, + "type": "object", + "title": "Created at", + "properties": { + "created_at": { + "$ref": "#/components/schemas/16_filter_conditions_date_time" + } + }, "description": "A filter on the list based on the object `created_at` field. The value is a dictionary with the following options: `before`, `after`. A date value must be presented in ISO 8601 format (`2016-11-16T14:14:31Z` or `2016-11-16`). An example: `[created_at][before]=2017-09-08T13:52:18.227Z`" }, "22_filter_name": { - "type": "object", - "title": "Name", - "properties": { - "name": { - "$ref": "#/components/schemas/16_filter_conditions_string" - } - }, + "type": "object", + "title": "Name", + "properties": { + "name": { + "$ref": "#/components/schemas/16_filter_conditions_string" + } + }, "description": "A filter on the list based on the name field." }, "22_filter_id": { - "type": "object", - "title": "ID", - "properties": { - "id": { - "$ref": "#/components/schemas/16_filter_conditions_string" - } - }, + "type": "object", + "title": "ID", + "properties": { + "id": { + "$ref": "#/components/schemas/16_filter_conditions_string" + } + }, "description": "A filter on the list based on the id of the location." }, "23_obj_qualification_object": { @@ -49929,42 +49928,42 @@ } } }, - "404": { - "description": "Returns an error if a resource is not found.", + "403": { + "description": "Returns an error if you don't have a specific credentials set up. Navigate to the **Dashboard** → **Project Settings** → **General** → **Integration Keys** to set up a pair of API keys and use them to send the request.", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/e_404_not_found" + "$ref": "#/components/schemas/e_integration_key" }, "examples": { - "Resource not found": { + "Example": { "value": { - "code": 404, - "key": "not_found", - "message": "Resource not found", - "details": "Cannot find customer with id cust_xqA7DGj5eYPHg6PHVKwYRWiA", - "request_id": "v-0c8b6b35294af6f192", - "resource_id": "cust_xqA7DGj5eYPHg6PHVKwYRWiA", - "resource_type": "customer" + "code": 403, + "message": "Forbidden", + "key": "integration_api_key_required" } } } } } }, - "403": { - "description": "Returns an error if you don't have a specific credentials set up. Navigate to the **Dashboard** → **Project Settings** → **General** → **Integration Keys** to set up a pair of API keys and use them to send the request.", + "404": { + "description": "Returns an error if a resource is not found.", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/e_integration_key" + "$ref": "#/components/schemas/e_404_not_found" }, "examples": { - "Example": { + "Resource not found": { "value": { - "code": 403, - "message": "Forbidden", - "key": "integration_api_key_required" + "code": 404, + "key": "not_found", + "message": "Resource not found", + "details": "Cannot find customer with id cust_xqA7DGj5eYPHg6PHVKwYRWiA", + "request_id": "v-0c8b6b35294af6f192", + "resource_id": "cust_xqA7DGj5eYPHg6PHVKwYRWiA", + "resource_type": "customer" } } } @@ -80894,7 +80893,7 @@ "tags": [ "QUALIFICATIONS API" ], - "summary": "Qualification Object [Beta]", + "summary": "Qualification Object", "description": "Data model description", "responses": { "200": { @@ -80916,7 +80915,7 @@ "tags": [ "QUALIFICATIONS API" ], - "summary": "Check Eligibility [Beta]", + "summary": "Check Eligibility", "description": "Generate a list of redeemables that are applicable in the context of the customer and order.\n\nThe new qualifications method is an improved version of [Campaign Qualifications](ref:examine-campaigns-qualification), [Voucher Qualifications](ref:examine-vouchers-qualification), and [Promotions Validation](ref:validate-promotions) API requests. The new qualification method introduces the following improvements:\n\n- Qualification results are returned faster\n- No limit on the number of returned redeemables\n- Introduces new qualification scenarios, not available in the previous version\n\n## Paging \n\nThe Voucherify Qualifications API request will return to you all of the redeemables available for the customer in batches of up to 50 redeemables. To get the next batch of redeemables, you need to use the `starting_after` cursor.\n\nTo process of paging the redeemables works in the following manner:\n\n- You send the first API request for Qualifications without the `starting_after` parameter.\n- The response will contain a parameter named `has_more`. If the parameter's value is set to `true`, then more redeemables are available.\n- Get the value of the `created_at` parameter of the last returned redeemable. The value of this parameter will be used as a cursor to retrieve the next page of redeemables.\n- Send another API request for Qualification with the `starting_after` parameter set to the value taken from the `created_at` parameter from the last returned redeemable.\n- Voucherify will return the next page of redeemables.\n- If the `has_more` parameter is set to `true`, apply steps 3-5 to get the next page of redeemables.", "parameters": [], "security": [ @@ -80955,7 +80954,7 @@ "tags": [ "QUALIFICATIONS API" ], - "summary": "Check Eligibility (client-side) [Beta]", + "summary": "Check Eligibility (client-side)", "description": "Generate a list of redeemables that are applicable in the context of the customer and order.\n\nThe new qualifications method is an improved version of [Campaign Qualifications](ref:examine-campaigns-qualification), [Voucher Qualifications](ref:examine-vouchers-qualification), and [Promotions Validation](ref:validate-promotions) API requests. The new qualification method introduces the following improvements:\n\n- Qualification results are returned faster\n- No limit on the number of returned redeemables\n- Introduces new qualification scenarios, not available in the previous version\n\n## Paging \n\nThe Voucherify Qualifications API request will return to you all of the redeemables available for the customer in batches of up to 50 redeemables. To get the next batch of redeemables, you need to use the `starting_after` cursor.\n\nTo process of paging the redeemables works in the following manner:\n\n- You send the first API request for Qualifications without the `starting_after` parameter.\n- The response will contain a parameter named `has_more`. If the parameter's value is set to `true`, then more redeemables are available.\n- Get the value of the `created_at` parameter of the last returned redeemable. The value of this parameter will be used as a cursor to retrieve the next page of redeemables.\n- Send another API request for Qualification with the `starting_after` parameter set to the value taken from the `created_at` parameter from the last returned redeemable.\n- Voucherify will return the next page of redeemables.\n- If the `has_more` parameter is set to `true`, apply steps 3-5 to get the next page of redeemables.", "parameters": [], "security": [ @@ -80989,4 +80988,4 @@ } } } -} +} \ No newline at end of file