feat: modify openapi spec at client generation time (#204)

* feat: Add feature to modify openapi spec at client generation time This is for temporary workaround (which are unfortunately very common). These should generally not be committed, so they have to be run from within the composite action * Run prettier
grafana · Jul 31, 2024 · fc84de9 · fc84de9
1 parent 528b401
commit fc84de9
Show file tree

Hide file tree

Showing 2 changed files with 75 additions and 14 deletions.
diff --git a/actions/generate-openapi-clients/README.md b/actions/generate-openapi-clients/README.md
@@ -6,14 +6,15 @@ _Note: For now, it only generates Go code. But it's structured in a way that any
 
 ## Inputs
 
-| Name              | Type    | Description                                                                                | Default Value                | Required |
-| ----------------- | ------- | ------------------------------------------------------------------------------------------ | ---------------------------- | -------- |
-| generator-version | string  | The version of the OpenAPI generator to use                                                | "7.7.0"                      | false    |
-| spec-path         | string  | The path to the OpenAPI spec to generate the client from. Supports JSON or YAML            | N/A                          | true     |
-| output-dir        | string  | The directory to output the generated client to                                            | "."                          | false    |
-| commit-changes    | boolean | If true, the action will commit and push the changes to the repository, if there's a diff. | true                         | false    |
-| commit-message    | string  | The commit message to use when committing the changes                                      | "Update clients and publish" | false    |
-| package-name      | string  | The name of the package to generate                                                        | N/A                          | true     |
+| Name               | Type    | Description                                                                                   | Default Value                | Required |
+| ------------------ | ------- | --------------------------------------------------------------------------------------------- | ---------------------------- | -------- |
+| generator-version  | string  | The version of the OpenAPI generator to use                                                   | "7.7.0"                      | false    |
+| spec-path          | string  | The path to the OpenAPI spec to generate the client from. Supports JSON or YAML               | N/A                          | true     |
+| output-dir         | string  | The directory to output the generated client to                                               | "."                          | false    |
+| commit-changes     | boolean | If true, the action will commit and push the changes to the repository, if there's a diff.    | true                         | false    |
+| commit-message     | string  | The commit message to use when committing the changes                                         | "Update clients and publish" | false    |
+| package-name       | string  | The name of the package to generate                                                           | N/A                          | true     |
+| modify-spec-script | string  | The path to an executable script that modifies the OpenAPI spec before generating the client. | ""                           | false    |
 
 ## Example workflow
 
@@ -33,9 +34,6 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 # v4.1.7
-      # Check out head_ref if working from a pull request
-      # with:
-      #   ref: ${{ github.head_ref }}
       - uses: actions/setup-go@0a12ed9d6a96ab950c8f026ed9f722fe0da7ef32 # v5.0.2
         with:
           go-version: 1.18
@@ -44,4 +42,44 @@ jobs:
         with:
           package-name: slo
           spec-path: openapi.yaml
+          modify-spec-script: .github/workflows/modify-spec.sh # Optional, see "Spec Modifications" section
 ```
+
+### Spec Modifications at Runtime
+
+The `modify-spec-script` attribute is the path to an executable script that modifies the OpenAPI spec before generating the client.
+The spec will be piped into the script and the script should output the modified spec to stdout.
+
+_Note: This is used as a workaround for the OpenAPI generator not supporting certain features. By using
+this feature, the spec will be modified temporarily, and the changes will not be committed._
+
+Here's an example of a modification script:
+
+```bash
+#! /usr/bin/env bash
+set -euo pipefail
+
+SCHEMA=`cat` # Read stdin
+modify() {
+    SCHEMA="$(echo "${SCHEMA}" | jq "${1}")"
+}
+modify '.components.schemas.FormattedApiApiKey.properties.id = { "anyOf": [ { "type": "string" }, { "type": "number" } ] }'
+modify '.components.schemas.FormattedApiApiKeyListResponse.properties.items.items.properties.id = { "anyOf": [ { "type": "string" }, { "type": "number" } ] }'
+modify '.components.schemas.FormattedOrgMembership.properties.allowGCloudTrial = { "anyOf": [ { "type": "boolean" }, { "type": "number" } ] }'
+modify '.components.schemas.FormattedApiOrgPublic.properties.allowGCloudTrial = { "anyOf": [ { "type": "boolean" }, { "type": "number" } ] }'
+modify '.paths["/v1/accesspolicies"].get.responses["200"].content["application/json"].schema = {
+  "type": "object",
+  "properties": {
+    "items": {
+      "type": "array",
+      "items": {
+        "$ref": "#/components/schemas/AuthAccessPolicy"
+      }
+    }
+  }
+}'
+
+echo "${SCHEMA}"
+```
+
+This script should be saved to a file and its path given in the `modify-spec-script` attribute.
diff --git a/actions/generate-openapi-clients/action.yaml b/actions/generate-openapi-clients/action.yaml
@@ -24,6 +24,14 @@ inputs:
   package-name:
     description: The name of the package to generate
     required: true
+  modify-spec-script:
+    description: |
+      The path to an executable script that modifies the OpenAPI spec before generating the client. 
+      The spec will be piped into the script and the script should output the modified spec to stdout.
+      Note: This is used as a workaround for the OpenAPI generator not supporting certain features. By using
+      this feature, the spec will be modified temporarily, and the changes will not be committed.
+    required: false
+    default: ""
 
 runs:
   using: composite
@@ -48,17 +56,32 @@ runs:
         key: openapi-generator-${{ inputs.generator-version }}
         path: openapi-generator-cli.jar
 
+    # Modify the spec if a script is provided
+    - shell: bash
+      run: |
+        if [ -n "${{ inputs.modify-spec-script }}" ]; then
+          cat "${{ inputs.spec-path }}" | "${{ inputs.modify-spec-script }}" > temp-spec.txt
+          echo "SPEC_PATH=temp-spec.txt" >> $GITHUB_ENV
+        else
+          echo "SPEC_PATH=${{ inputs.spec-path }}" >> $GITHUB_ENV
+        fi
+      env:
+        SPEC_PATH: ${{ inputs.spec-path }}
+
     # Generate the client
     - shell: bash
       run: ${GITHUB_ACTION_PATH}/generate.sh
       env:
-        SPEC_PATH: ${{ inputs.spec-path }}
         OUTPUT_DIR: ${{ inputs.output-dir }}
         PACKAGE_NAME: ${{ inputs.package-name }}
 
-    # Delete the openapi-generator-cli.jar file (it shouldn't be committed)
+    # Cleanup files that shouldn't be committed
     - shell: bash
-      run: rm openapi-generator-cli.jar
+      run: |
+        rm openapi-generator-cli.jar
+        if [ -n "${{ inputs.modify-spec-script }}" ]; then
+          rm temp-spec.txt
+        fi
 
     # Commit the changes
     - uses: stefanzweifel/git-auto-commit-action@8621497c8c39c72f3e2a999a26b4ca1b5058a842 # v5.0.1