CUT-5162: Inject x-powershell-method-name

[gweinjc]

Issues

• CUT-5162 - Inject x-powershell-method-name

What does this solve?

Created Add-OasMethodName

• Functions purpose is to set a given operationID's function name that is defined in the mapping.json by injecting the x-powershell-method-name header into the OAS under that operationID.

Is there anything particularly tricky?

With the recent combination of the V1 and V2 endpoints into a singular OAS, I had to rework the mapping generation process due to the size of the OAS.

Also adjusted the docker script to remove the java requirement and openapi-generator requirement as they're redundant.

How should this be tested?

1. Delete any .json files located in the /OpenAPI/OAS directory
   a. Example: JumpCloud.SDK.DirectoryInsights.json
2. Get the latest JumpCloud.SDK.DirectoryInsights.json file from the private URL (https://docs.internal.jumpcloud.io/new/external/api/insights/directory/index.html)
3. New Mapping Generation

# CD into the Scripts folder
cd '/Users/USERNAME/Documents/GitHub/jcapi-powershell/OpenAPI/scripts' 

# Import the function(s)
. '/Users/USERNAME/Documents/GitHub/jcapi-powershell/OpenAPI/scripts/OASFunctions.ps1'

# Run the function
Update-OasMapping

4. Find the OpenAPI/OAS/mapping/OASMapping.DirectoryInsights.json
5. Add values to the x-powershell-method-name property for each of the OperationIDs (They can be placeholders for testing). Example:

"directoryInsights_eventsCountPost": {
    "paginate": false,
    "method": "post",
    "x-powershell-method-name": "Get-JcSdkEventCount",
    "path": "/events/count"
  }

6. Run the Add-OasMethodName function

Add-OasMethodName -SdkName 'DirectoryInsights'

7. Open the OpenAPI/OAS/JumpCloud.SDK.DirectoryInsights.json and validate that the x-powershell-method-name was added for each of the operationIDs that you specified

Screenshots

---

Note

Low Risk
Changes affect OpenAPI/SDK build scripts and generated spec metadata only, not runtime API or security behavior.

Overview
This PR extends the OpenAPI → PowerShell SDK pipeline so each operation can carry a stable cmdlet name via the x-powershell-method-name extension.

Add-OasMethodName reads per-SDK OASMapping.*.json files and writes (or updates) that extension on the matching path/method in JumpCloud.SDK.*.json, keyed by operationId. Update-OasMapping was adjusted to build and merge mapping entries at scale—needed after V1 and V2 were combined into larger single specs— including placeholder x-powershell-method-name values on new operations.

Supporting changes include Docker/build script simplification (dropping redundant Java and openapi-generator steps) and a temporary OpenAPI/.gitignore entry for /PowerShell/* while OAS manipulation scripts are developed locally.

^{Reviewed by Cursor Bugbot for commit 20822f5. Bugbot is set up for automated code reviews on this repo. Configure here.}

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{Reviewed by Cursor Bugbot for commit ba9b91b. Configure here.}

[cursor]

Temporary gitignore risks permanently hiding generated SDK output

Medium Severity

The comment explicitly says "Temp ignore" but this is being merged into the main branch. The /PowerShell/* pattern will prevent any newly generated SDK files under OpenAPI/PowerShell/ from being tracked by git. The readme.md and generate-powershell-docker.mjs both show this directory is the intended output location for generated SDKs. If this .gitignore is forgotten, future SDK regeneration output will silently go untracked.

 

^{Reviewed by Cursor Bugbot for commit ba9b91b. Configure here.}

[edgar-lins]

Tested following the steps in the description on the DirectoryInsights SDK:

• Regenerated the mapping with Update-OasMapping
• Set x-powershell-method-name for 3 operationIDs (placeholders), left the other 4 empty
• Ran Add-OasMethodName -SdkName 'DirectoryInsights'

The 3 populated names were correctly injected into JumpCloud.SDK.DirectoryInsights.json at the right operationIDs. Works as expected for the main use case.

One observation: the function also injects the header for entries with an empty x-powershell-method-name, so the 4 empty ones ended up as "x-powershell-method-name": "" in the OAS spec. The comparison on the insertion check is just -ne against the existing value, so it doesn't skip empty entries.

Is that intentional? Does the SDK generator handle an empty x-powershell-method-name gracefully (fall back to the default name), or would it be cleaner to skip empty entries here? Not blocking — approving — just want to confirm the expected behavior downstream.

[gweinjc]

Tested following the steps in the description on the DirectoryInsights SDK:

• Regenerated the mapping with Update-OasMapping
• Set x-powershell-method-name for 3 operationIDs (placeholders), left the other 4 empty
• Ran Add-OasMethodName -SdkName 'DirectoryInsights'

The 3 populated names were correctly injected into JumpCloud.SDK.DirectoryInsights.json at the right operationIDs. Works as expected for the main use case.

One observation: the function also injects the header for entries with an empty x-powershell-method-name, so the 4 empty ones ended up as "x-powershell-method-name": "" in the OAS spec. The comparison on the insertion check is just -ne against the existing value, so it doesn't skip empty entries.

Is that intentional? Does the SDK generator handle an empty x-powershell-method-name gracefully (fall back to the default name), or would it be cleaner to skip empty entries here? Not blocking — approving — just want to confirm the expected behavior downstream.

Yes this is intentional. The x-powershell-method-name will never be blank in the mapping file. We're going to have a CI test to validate that all of them are filled when making pull requests in the future