feat(spec): commit bundled specs (#134)

Author: shortcuts

.github/actions/cache/action.yml

@@ -17,28 +17,23 @@ inputs:
 runs:
   using: composite
   steps:
-    # restore specs
-    - name: Restore built ${{ inputs.spec }} spec
-      if: ${{ inputs.job == 'client' }}
-      uses: actions/cache@v2
-      with:
-        path: /home/runner/work/api-clients-automation/api-clients-automation/specs/dist/${{ inputs.spec }}.yml
-        key: ${{ runner.os }}-${{ inputs.spec }}-specs-${{ hashFiles(format('specs/{0}/**', inputs.spec)) }}
-
     # restore clients
     - name: Restore built JavaScript common client
+      if: ${{ inputs.job == 'cts' }}
       uses: actions/cache@v2
       with:
         path: /home/runner/work/api-clients-automation/api-clients-automation/clients/algoliasearch-client-javascript/packages/client-common/dist
         key: ${{ runner.os }}-1-js-client-common-${{ hashFiles('clients/algoliasearch-client-javascript/packages/client-common/**') }}
 
     - name: Restore built JavaScript node requester
+      if: ${{ inputs.job == 'cts' }}
       uses: actions/cache@v2
       with:
         path: /home/runner/work/api-clients-automation/api-clients-automation/clients/algoliasearch-client-javascript/packages/requester-node-http/dist
         key: ${{ runner.os }}-1-js-node-requester-${{ hashFiles('clients/algoliasearch-client-javascript/packages/requester-node-http/**') }}
 
     - name: Restore built JavaScript browser requester
+      if: ${{ inputs.job == 'cts' }}
       uses: actions/cache@v2
       with:
         path: /home/runner/work/api-clients-automation/api-clients-automation/clients/algoliasearch-client-javascript/packages/requester-browser-xhr/dist
@@ -49,56 +44,56 @@ runs:
       uses: actions/cache@v2
       with:
         path: /home/runner/work/api-clients-automation/api-clients-automation/clients/algoliasearch-client-javascript/packages/client-search/dist
-        key: ${{ runner.os }}-1-js-client-search-${{ hashFiles('clients/algoliasearch-client-javascript/packages/client-search/**') }}-${{ hashFiles('specs/dist/search.yml') }}
+        key: ${{ runner.os }}-1-js-client-search-${{ hashFiles('clients/algoliasearch-client-javascript/packages/client-search/**') }}-${{ hashFiles('specs/bundled/search.yml') }}
 
     - name: Restore built JavaScript recommend client
       if: ${{ inputs.job == 'cts' }}
       uses: actions/cache@v2
       with:
         path: /home/runner/work/api-clients-automation/api-clients-automation/clients/algoliasearch-client-javascript/packages/recommend/dist
-        key: ${{ runner.os }}-1-js-client-recommend-${{ hashFiles('clients/algoliasearch-client-javascript/packages/recommend/**') }}-${{ hashFiles('specs/dist/recommend.yml') }}
+        key: ${{ runner.os }}-1-js-client-recommend-${{ hashFiles('clients/algoliasearch-client-javascript/packages/recommend/**') }}-${{ hashFiles('specs/bundled/recommend.yml') }}
 
     - name: Restore built JavaScript query-suggestions client
       if: ${{ inputs.job == 'cts' }}
       uses: actions/cache@v2
       with:
         path: /home/runner/work/api-clients-automation/api-clients-automation/clients/algoliasearch-client-javascript/packages/client-query-suggestions/dist
-        key: ${{ runner.os }}-1-js-client-query-suggestions-${{ hashFiles('clients/algoliasearch-client-javascript/packages/client-query-suggestions/**') }}-${{ hashFiles('specs/dist/query-suggestions.yml') }}
+        key: ${{ runner.os }}-1-js-client-query-suggestions-${{ hashFiles('clients/algoliasearch-client-javascript/packages/client-query-suggestions/**') }}-${{ hashFiles('specs/bundled/query-suggestions.yml') }}
 
     - name: Restore built JavaScript personalization client
       if: ${{ inputs.job == 'cts' }}
       uses: actions/cache@v2
       with:
         path: /home/runner/work/api-clients-automation/api-clients-automation/clients/algoliasearch-client-javascript/packages/client-personalization/dist
-        key: ${{ runner.os }}-1-js-client-personalization-${{ hashFiles('clients/algoliasearch-client-javascript/packages/client-personalization/**') }}-${{ hashFiles('specs/dist/personalization.yml') }}
+        key: ${{ runner.os }}-1-js-client-personalization-${{ hashFiles('clients/algoliasearch-client-javascript/packages/client-personalization/**') }}-${{ hashFiles('specs/bundled/personalization.yml') }}
 
     - name: Restore built JavaScript analytics client
       if: ${{ inputs.job == 'cts' }}
       uses: actions/cache@v2
       with:
         path: /home/runner/work/api-clients-automation/api-clients-automation/clients/algoliasearch-client-javascript/packages/client-analytics/dist
-        key: ${{ runner.os }}-1-js-client-analytics-${{ hashFiles('clients/algoliasearch-client-javascript/packages/client-analytics/**') }}-${{ hashFiles('specs/dist/analytics.yml') }}
+        key: ${{ runner.os }}-1-js-client-analytics-${{ hashFiles('clients/algoliasearch-client-javascript/packages/client-analytics/**') }}-${{ hashFiles('specs/bundled/analytics.yml') }}
 
     - name: Restore built JavaScript abtesting client
       if: ${{ inputs.job == 'cts' }}
       uses: actions/cache@v2
       with:
         path: /home/runner/work/api-clients-automation/api-clients-automation/clients/algoliasearch-client-javascript/packages/client-abtesting/dist
-        key: ${{ runner.os }}-1-js-client-abtesting-${{ hashFiles('clients/algoliasearch-client-javascript/packages/client-abtesting/**') }}-${{ hashFiles('specs/dist/abtesting.yml') }}
+        key: ${{ runner.os }}-1-js-client-abtesting-${{ hashFiles('clients/algoliasearch-client-javascript/packages/client-abtesting/**') }}-${{ hashFiles('specs/bundled/abtesting.yml') }}
 
     - name: Restore built JavaScript insights client
       if: ${{ inputs.job == 'cts' }}
       uses: actions/cache@v2
       with:
         path: /home/runner/work/api-clients-automation/api-clients-automation/clients/algoliasearch-client-javascript/packages/client-insights/dist
-        key: ${{ runner.os }}-1-js-client-insights-${{ hashFiles('clients/algoliasearch-client-javascript/packages/client-insights/**') }}-${{ hashFiles('specs/dist/insights.yml') }}
+        key: ${{ runner.os }}-1-js-client-insights-${{ hashFiles('clients/algoliasearch-client-javascript/packages/client-insights/**') }}-${{ hashFiles('specs/bundled/insights.yml') }}
 
     - name: Restore built JavaScript sources client
       if: ${{ inputs.job == 'cts' }}
       uses: actions/cache@v2
       with:
         path: /home/runner/work/api-clients-automation/api-clients-automation/clients/algoliasearch-client-javascript/packages/client-sources/dist
-        key: ${{ runner.os }}-1-js-client-sources-${{ hashFiles('clients/algoliasearch-client-javascript/packages/client-sources/**') }}-${{ hashFiles('specs/dist/sources.yml') }}
+        key: ${{ runner.os }}-1-js-client-sources-${{ hashFiles('clients/algoliasearch-client-javascript/packages/client-sources/**') }}-${{ hashFiles('specs/bundled/sources.yml') }}
 
     - name: Restore built JavaScript predict client
       if: ${{ inputs.job == 'cts' }}
@@ -112,7 +107,7 @@ runs:
       uses: actions/cache@v2
       with:
         path: /home/runner/work/api-clients-automation/api-clients-automation/clients/algoliasearch-client-java-2/target
-        key: ${{ runner.os }}-1-java-client-${{ hashFiles('clients/algoliasearch-client-java-2/**') }}-${{ hashFiles('specs/dist/search.yml') }}
+        key: ${{ runner.os }}-1-java-client-${{ hashFiles('clients/algoliasearch-client-java-2/**') }}-${{ hashFiles('specs/bundled/search.yml') }}
 
     # setup yarn
     - name: Get yarn cache directory path

.github/workflows/check.yml

@@ -55,17 +55,12 @@ jobs:
       - name: Restore cache
         uses: ./.github/actions/cache
 
-      - name: Cache ${{ matrix.client }} spec
-        id: cache
-        uses: actions/cache@v2
-        with:
-          path: '/home/runner/work/api-clients-automation/api-clients-automation/specs/dist/${{ matrix.client }}.yml'
-          key: ${{ runner.os }}-${{ matrix.client }}-specs-${{ hashFiles(format('specs/{0}/**', matrix.client)) }}
-
       - name: Building ${{ matrix.client }} specs
-        if: steps.cache.outputs.cache-hit != 'true'
         run: yarn build:specs ${{ matrix.client }}
 
+      - name: Check diff with pushed spec
+        run: exit $(git status --porcelain specs/bundled/${{ matrix.client }}.yml | wc -l)
+
   client_javascript:
     timeout-minutes: 10
     runs-on: ubuntu-20.04
@@ -89,7 +84,7 @@ jobs:
         uses: actions/cache@v2
         with:
           path: '/home/runner/work/api-clients-automation/api-clients-automation/${{ matrix.client.folder }}/dist'
-          key: ${{ runner.os }}-1-js-client-${{ matrix.client.name }}-${{ hashFiles(format('{0}/**', matrix.client.folder)) }}-${{ hashFiles(format('specs/dist/{0}.yml', matrix.client.name)) }}
+          key: ${{ runner.os }}-1-js-client-${{ matrix.client.name }}-${{ hashFiles(format('{0}/**', matrix.client.folder)) }}-${{ hashFiles(format('specs/bundled/{0}.yml', matrix.client.name)) }}
 
       - name: Generate ${{ matrix.client.name }} client
         if: steps.cache.outputs.cache-hit != 'true'
@@ -127,7 +122,7 @@ jobs:
         uses: actions/cache@v2
         with:
           path: '/home/runner/work/api-clients-automation/api-clients-automation/${{ matrix.client.folder }}/target'
-          key: ${{ runner.os }}-1-java-client-${{ matrix.client.name }}-${{ hashFiles(format('{0}/**', matrix.client.folder)) }}-${{ hashFiles(format('specs/dist/{0}.yml', matrix.client.name)) }}
+          key: ${{ runner.os }}-1-java-client-${{ matrix.client.name }}-${{ hashFiles(format('{0}/**', matrix.client.folder)) }}-${{ hashFiles(format('specs/bundled/{0}.yml', matrix.client.name)) }}
 
       - name: Generate ${{ matrix.client.name }} client
         if: steps.cache.outputs.cache-hit != 'true'

.gitignore

@@ -1,7 +1,6 @@
 node_modules
 .bash_profile
 .env
-dist
 .pnp.cjs
 
 yarn-error.log
@@ -18,4 +17,6 @@ target
 .gradle
 build
 
+dist
+
 .openapi-generator

doc/CTS.md

@@ -46,9 +46,9 @@ The test generation script requires a JSON file name from the `operationId` (e.g
       "searchParam": {
         "$objectName": "the name of the object for strongly type language, should be on every 'object' type (can be 'Object' if free-form)",
         "query": "the string to search",
-        "acl": { 
+        "acl": {
           "$enumType": "the name of the enum object if marked as enum in the spec",
-          "value": "the string value of the enum",
+          "value": "the string value of the enum"
         }
       }
     },
@@ -117,6 +117,6 @@ When writing your template, here is a list of variables accessible from `mustach
 To get the list of `operationId` not yet in the CTS but in the spec, run this command:
 
 ```bash
-rm -rf ./specs/dist
+rm -rf ./specs/bundled
 comm -3 <(grep -r operationId ./specs | awk -F: '{gsub(/ /,""); print $NF}' | sort) <(find ./tests/CTS/clients -type f -name '*.json' | awk -F/ '{gsub(/.json/,"");print $NF}' | sort)
 ```

openapitools.json

@@ -9,7 +9,7 @@
         "config": "#{cwd}/openapitools.json",
         "apiPackage": "src",
         "output": "#{cwd}/clients/algoliasearch-client-javascript/packages/client-search",
-        "glob": "specs/dist/search.yml",
+        "glob": "specs/bundled/search.yml",
         "gitHost": "algolia",
         "gitUserId": "algolia",
         "gitRepoId": "algoliasearch-client-javascript",
@@ -30,7 +30,7 @@
         "config": "#{cwd}/openapitools.json",
         "apiPackage": "src",
         "output": "#{cwd}/clients/algoliasearch-client-javascript/packages/recommend",
-        "glob": "specs/dist/recommend.yml",
+        "glob": "specs/bundled/recommend.yml",
         "gitHost": "algolia",
         "gitUserId": "algolia",
         "gitRepoId": "algoliasearch-client-javascript",
@@ -51,7 +51,7 @@
         "config": "#{cwd}/openapitools.json",
         "apiPackage": "src",
         "output": "#{cwd}/clients/algoliasearch-client-javascript/packages/client-personalization",
-        "glob": "specs/dist/personalization.yml",
+        "glob": "specs/bundled/personalization.yml",
         "gitHost": "algolia",
         "gitUserId": "algolia",
         "gitRepoId": "algoliasearch-client-javascript",
@@ -75,7 +75,7 @@
         "config": "#{cwd}/openapitools.json",
         "apiPackage": "src",
         "output": "#{cwd}/clients/algoliasearch-client-javascript/packages/client-analytics",
-        "glob": "specs/dist/analytics.yml",
+        "glob": "specs/bundled/analytics.yml",
         "gitHost": "algolia",
         "gitUserId": "algolia",
         "gitRepoId": "algoliasearch-client-javascript",
@@ -100,7 +100,7 @@
         "config": "#{cwd}/openapitools.json",
         "apiPackage": "src",
         "output": "#{cwd}/clients/algoliasearch-client-javascript/packages/client-insights",
-        "glob": "specs/dist/insights.yml",
+        "glob": "specs/bundled/insights.yml",
         "gitHost": "algolia",
         "gitUserId": "algolia",
         "gitRepoId": "algoliasearch-client-javascript",
@@ -125,7 +125,7 @@
         "config": "#{cwd}/openapitools.json",
         "apiPackage": "src",
         "output": "#{cwd}/clients/algoliasearch-client-javascript/packages/client-abtesting",
-        "glob": "specs/dist/abtesting.yml",
+        "glob": "specs/bundled/abtesting.yml",
         "gitHost": "algolia",
         "gitUserId": "algolia",
         "gitRepoId": "algoliasearch-client-javascript",
@@ -150,7 +150,7 @@
         "config": "#{cwd}/openapitools.json",
         "apiPackage": "src",
         "output": "#{cwd}/clients/algoliasearch-client-javascript/packages/client-query-suggestions",
-        "glob": "specs/dist/query-suggestions.yml",
+        "glob": "specs/bundled/query-suggestions.yml",
         "gitHost": "algolia",
         "gitUserId": "algolia",
         "gitRepoId": "algoliasearch-client-javascript",
@@ -174,7 +174,7 @@
         "config": "#{cwd}/openapitools.json",
         "apiPackage": "src",
         "output": "#{cwd}/clients/algoliasearch-client-javascript/packages/client-sources",
-        "glob": "specs/dist/sources.yml",
+        "glob": "specs/bundled/sources.yml",
         "gitHost": "algolia",
         "gitUserId": "algolia",
         "gitRepoId": "algoliasearch-client-javascript",
@@ -224,7 +224,7 @@
         "invokerPackage": "com.algolia",
         "modelPackage": "com.algolia.model",
         "library": "okhttp-gson",
-        "glob": "specs/dist/search.yml",
+        "glob": "specs/bundled/search.yml",
         "gitHost": "algolia",
         "gitUserId": "algolia",
         "gitRepoId": "algoliasearch-client-java-2",
@@ -240,7 +240,7 @@
         "templateDir": "#{cwd}/templates/php/",
         "config": "#{cwd}/openapitools.json",
         "output": "#{cwd}/clients/algoliasearch-client-php",
-        "glob": "specs/dist/search.yml",
+        "glob": "specs/bundled/search.yml",
         "gitHost": "algolia",
         "gitUserId": "algolia",
         "gitRepoId": "algoliasearch-client-php",
@@ -258,7 +258,7 @@
         "templateDir": "#{cwd}/templates/php/",
         "config": "#{cwd}/openapitools.json",
         "output": "#{cwd}/clients/algoliasearch-client-php",
-        "glob": "specs/dist/recommend.yml",
+        "glob": "specs/bundled/recommend.yml",
         "gitHost": "algolia",
         "gitUserId": "algolia",
         "gitRepoId": "algoliasearch-client-php",
@@ -276,7 +276,7 @@
         "templateDir": "#{cwd}/templates/php/",
         "config": "#{cwd}/openapitools.json",
         "output": "#{cwd}/clients/algoliasearch-client-php",
-        "glob": "specs/dist/personalization.yml",
+        "glob": "specs/bundled/personalization.yml",
         "gitHost": "algolia",
         "gitUserId": "algolia",
         "gitRepoId": "algoliasearch-client-php",
@@ -298,7 +298,7 @@
         "templateDir": "#{cwd}/templates/php/",
         "config": "#{cwd}/openapitools.json",
         "output": "#{cwd}/clients/algoliasearch-client-php",
-        "glob": "specs/dist/analytics.yml",
+        "glob": "specs/bundled/analytics.yml",
         "gitHost": "algolia",
         "gitUserId": "algolia",
         "gitRepoId": "algoliasearch-client-php",
@@ -321,7 +321,7 @@
         "templateDir": "#{cwd}/templates/php/",
         "config": "#{cwd}/openapitools.json",
         "output": "#{cwd}/clients/algoliasearch-client-php",
-        "glob": "specs/dist/insights.yml",
+        "glob": "specs/bundled/insights.yml",
         "gitHost": "algolia",
         "gitUserId": "algolia",
         "gitRepoId": "algoliasearch-client-php",
@@ -344,7 +344,7 @@
         "templateDir": "#{cwd}/templates/php/",
         "config": "#{cwd}/openapitools.json",
         "output": "#{cwd}/clients/algoliasearch-client-php",
-        "glob": "specs/dist/abtesting.yml",
+        "glob": "specs/bundled/abtesting.yml",
         "gitHost": "algolia",
         "gitUserId": "algolia",
         "gitRepoId": "algoliasearch-client-php",
@@ -367,7 +367,7 @@
         "templateDir": "#{cwd}/templates/php/",
         "config": "#{cwd}/openapitools.json",
         "output": "#{cwd}/clients/algoliasearch-client-php",
-        "glob": "specs/dist/query-suggestions.yml",
+        "glob": "specs/bundled/query-suggestions.yml",
         "gitHost": "algolia",
         "gitUserId": "algolia",
         "gitRepoId": "algoliasearch-client-php",

scripts/builds/specs.sh

@@ -25,17 +25,17 @@ check_format_spec() {
 
 build_spec() {
     local client=$1
-    yarn openapi bundle specs/${client}/spec.yml -o specs/dist/${client}.${OUTPUT} --ext ${OUTPUT}
+    yarn openapi bundle specs/${client}/spec.yml -o specs/bundled/${client}.${OUTPUT} --ext ${OUTPUT}
     echo ""
 }
 
 validate_output_spec() {
     local client=$1
-    yarn openapi lint specs/dist/${client}.${OUTPUT}
+    yarn openapi lint specs/bundled/${client}.${OUTPUT}
     echo ""
 }
 
-CLIENTS=$(find specs/*/spec.yml | awk -F / '{ print $(NF-1) }')
+CLIENTS=($(find specs/*/spec.yml | awk -F / '{ print $(NF-1) }'))
 
 if [[ $CLIENT == "all" ]]; then
     CLIENTS=("${CLIENTS[@]}")

scripts/generate.sh

@@ -20,8 +20,9 @@ compute_hash() {
 # build spec before generating client
 build_spec() {
     # check if file and cache exist
+    mkdir -p specs/dist
     cacheFile="specs/dist/$CLIENT.cache"
-    if [[ -f specs/dist/$CLIENT.yml ]]; then
+    if [[ -f specs/bundled/$CLIENT.yml ]]; then
         cache=$(compute_hash)
         # compare with stored cache
         if [[ -f $cacheFile && $(cat $cacheFile) == $cache ]]; then

scripts/pre-gen/setHostsOptions.ts

@@ -43,7 +43,7 @@ async function setHostsOptions(): Promise<void> {
     throw new Error(`Generator not found: ${generator}`);
   }
 
-  const specPath = path.join(__dirname, `../../specs/dist/${client}.yml`);
+  const specPath = path.join(__dirname, `../../specs/bundled/${client}.yml`);
 
   if (!(await stat(specPath))) {
     throw new Error(`File not found ${specPath}`);

specs/bundled/README.md

@@ -0,0 +1,11 @@
+# Bundled specs
+
+**Please do not edit the files in this folder, they are generated and changes will be overwritten on next use**
+
+Output folder of the specs located in `/specs/<CLIENT_NAME>/spec.yml`.
+
+This folder hosts the bundled specs used to:
+
+- Generate clients.
+- Generate documentation.
+- Share single readable spec file for a specific client.