From 0b845d5ea1527a510a2744935dfbabfb52ac12bc Mon Sep 17 00:00:00 2001 From: Christian Lechner Date: Tue, 10 Jan 2023 12:09:56 +0100 Subject: [PATCH] updated docu for JSON Schema association --- README.md | 2 +- docs/FAQ.md | 2 +- docs/PARAMETERS_OVERVIEW.md | 42 +++++++++++++++++++++++++++++++++++++ docs/SAMPLECONFIG.md | 3 +-- parameters.json | 2 +- 5 files changed, 46 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index e4ace400..b77230f6 100644 --- a/README.md +++ b/README.md @@ -27,7 +27,7 @@ Started as a small helper for basic SAP BTP setups the tool has grown since its - [Overview](./docs/OVERVIEW.md) - [Basic setup](./docs/BASIC_SETUP.md) incl. the prerequisites -- [Detailed walk-though](./docs/README.md) +- [Detailed walk-through](./docs/README.md) - [Detailed configuration](./docs/SAMPLECONFIG.md) - [Overview of btpsa parameters](./docs/PARAMETERS_OVERVIEW.md) - [FAQ](./docs/FAQ.md) diff --git a/docs/FAQ.md b/docs/FAQ.md index da512152..5e274d0b 100644 --- a/docs/FAQ.md +++ b/docs/FAQ.md @@ -252,7 +252,7 @@ You can now download the `kubeconfig`file either via the Kyma dashboard or via t * Open the Service Account created by you in the previous step. * Download kubeconfig and store it -* Via the script +* Via the script * If using Mac set the execute permission on the file `templates/kubeconfig-sa-mac.sh` and run it: diff --git a/docs/PARAMETERS_OVERVIEW.md b/docs/PARAMETERS_OVERVIEW.md index 7c5c68ca..45460988 100644 --- a/docs/PARAMETERS_OVERVIEW.md +++ b/docs/PARAMETERS_OVERVIEW.md @@ -8,3 +8,45 @@ As we have seen the setup-automator is configured via the `parameters.json` and *Be ware that the documentation is generated via [JSON Schema Markdown Tools](https://github.com/adobe/jsonschema2md) which gives us some rough edges in the documentation when it comes to the allowed values.* > 📝 Tip - The `parameters.json` and the `usecase.json` files are backed by a [JSON schema](https://json-schema.org/). This helps you when editing the files via type-ahead support, so no need to have the documentation open side-by-side to check for possible values. Indeed the documentation is generated based on the JSON schemas. + +## JSON schemas and IDEs + +The `parameters.json` as well as the `usecase.json` files reference the corresponding JSON schemas directly in the code like: + +```json +{ + "$schema": "https://raw.githubusercontent.com/SAP-samples/btp-setup-automator/main/libs/btpsa-parameters.json", + "usecasefile": "usecases/released/default.json", + ... +} +``` + +This ensures that the features and support provided by the schema are available for you, no matter which IDE you are using. + +In addition every IDE offers additional approaches to reference a JSON schema for a specific IDE e.g., in [WebStorm](https://www.jetbrains.com/help/webstorm/json.html#ws_json_using_schemas). Using one of the alternatives makes the explicit reference to the JSON schema obsolete. + +In case of VS Code the [configuration](https://code.visualstudio.com/docs/languages/json#_mapping-in-the-user-settings) can be done via the `.vscode/settings.json` file in this repository: + +```JSON +{ +... +"json.schemas": [ + { + "fileMatch": [ + "*usecase.json" + ], + "url": "https://raw.githubusercontent.com/SAP-samples/btp-setup-automator/main/libs/btpsa-usecase.json" + }, + { + "fileMatch": [ + "*parameters.json" + ], + "url": "https://raw.githubusercontent.com/SAP-samples/btp-setup-automator/main/libs/btpsa-parameters.json" + } + ] +} +``` + +This configuration makes use of the [file match syntax](https://code.visualstudio.com/docs/languages/json#_file-match-syntax) to identify the relevant JSON files. With VS Code and this configuration in place you can omit referencing the JSON schema in your own `parameters.json` and `usecase.json` files. + +> ⚠ Note - To stay backwards compatible and support the IDE of your choice we stick to referencing the JSON schema explicitly. The `parameters.json` and `usecase.json` do as of today not consistently adhere to the file name matching needed for the configuration. However feel free to adopt the setup in your personal configurations. diff --git a/docs/SAMPLECONFIG.md b/docs/SAMPLECONFIG.md index 502269ce..23e7dd72 100644 --- a/docs/SAMPLECONFIG.md +++ b/docs/SAMPLECONFIG.md @@ -229,14 +229,13 @@ btpsa will expose account metadata as environment variables to allow you to refe - `$SUBDOMAIN`: Subaccount subdomain - `$SUBACCOUNT`: Subaccount name - If the usecase involves Kyma, `$KYMAKUBECONFIGURL` is also available (e.g.: `https://kyma-env-broker.cp.kyma.cloud.sap/kubeconfig/`). And for Cloud Foundry: - `$CFAPIENDPOINT`: e.g.: `https://api.cf.us10-001.hana.ondemand.com` - `$ORG`: Org name -- `$ORGID`: Org ID +- `$ORGID`: Org ID The only environment variable available for `executeBeforeAccountSetup` is `$GLOBAL_ACCOUNT_ID`. diff --git a/parameters.json b/parameters.json index 9cf6c121..b1732914 100644 --- a/parameters.json +++ b/parameters.json @@ -10,7 +10,7 @@ "envvariables": { "BTPSA_YOUR_OWN_ENV_VARIABLE1": "Hi! I'm BTPSA!", "BTPSA_YOUR_OWN_ENV_VARIABLE2": "How are you doing?", - "BTPSA_YOUR_OWN_ENV_VARIABLE3": "You can use these variables in any command within the `executeBeforeAccountSetup` and `executeAfterAccountSetup` section by accessing (and manupulating) them as an OS environment variable!" + "BTPSA_YOUR_OWN_ENV_VARIABLE3": "You can use these variables in any command within the `executeBeforeAccountSetup` and `executeAfterAccountSetup` section by accessing (and manipulating) them as an OS environment variable!" }, "myusergroups": [ {