Generate PowerShellSDK using openapi-generator

OpenAPI generator generates the client side PowerShellSDK by given a OpenAPI document. PowerShellSDK generated by the openapi-generator can be used out of the box without any changes.

Here is the some benefit of powershell sdk

1. No dependency on c# code. It is pure PowerShell script.
2. HTTPSigning supported out of the box for RSA and ECDSA key.
3. Cookies and API Key Auth supported.
4. It is based on OpenAPI Spec 3.0.1.
5. Generated Sdk is compatible with PowerShell 5.1 and above, It is recommended to use PowerShell v7.

I want to give a little highlight for openapi-generator, It is build upon java , it provides SDK generator for most of the languages. One can check the supported language with following command.

Java -jar ./openapi-generator-cli.jar list

see the help related to sdk generator by using below command

Java -jar ./openapi-generator-cli.jar help generate

To generate the PowerShell SDK I am referring the Petstore OpenAPI document which can be found at below link.

OpenAPITools/openapi-generator

Command to generate the PowerShell SDK

Java -jar ./openapi-generator-cli.jar generate -i ./Petstore.yaml -o ./Petstore-PowerShellSDK -c .\PowerShellConfig.Yaml -g powershell

Here is the brief of parameter used for sdk generation

• generate :- Command to generate the SDK
• -g or — generator-name :- specify the generator name (refer to the command for list of supported languages)

java ./openapi-generator-cli.jar list

• -i or — input-spec :- Location of the OpenAPI document , it can be a url or file path
• -o or — output :- Specify the output directory where to write the generated files.
• -c or — config :- specify the language specific configurations. it can be yaml or json file. for more about the configuration files refer to below command. it is an optional parameter.

java -jar ./openapi-generator-cli.jar config-help -g powershell 

Here is the sample config file for PowerShellSDK

#Package guid to uniquely identify the module.
packageGuid: e4848b95-3695-4d55-92b9-744a153d2bc7
#User can map the Verbs as per PowerShell supported verbs.Like below #PowerShell does not support the Verb Delete so it is mapped with #the verb Remove
commonVerbs: Delete=Remove:Patch=Update
#Module package version
packageVersion: 1.0.2
#Module name 
packageName: PSPetstore
#PowerShell gallery url if module is published on PowerShell gallery
powershellGalleryUrl: https://www.powershellgallery.com/packages/PSPetstore
#Prefix for the cmdlet
apiNamePrefix: PS
#Minimum supported PowerShell version.
powershellVersion: "7.0"

Once the PowerShellSDK is generated, user needs to run the Build.ps1 script which generates the.psd1 file for the generated module.

The generated PowerShellSDK has following folder layout.

├───.openapi-generator
├───docs
├───src
│   └───PSPetstore
│       ├───Api
│       ├───Client
│       ├───en-US
│       ├───Model
│       └───Private
└───tests
    ├───Api
    └───Model

Here is the brief of the above folder layout

docs :- It contains the generated docs for API and Model

src :- This folder contains the generated PowerShell SDK, The folder Api contains the Cmdlet to perform the operation. The folder Model contains the model based on the OpenAPI doc schema. It contains ConvertTo-<Name> and Initialize-<Name> cmdlets. ConevrtTo-<Name> cmdlets are internally used by the API cmldets to validate the server response as per OpebAPI doc. The Initiailize-<Noun> cmdlet is used to generate the PSObject which can be directly passed to the cmdlet (New and Set cmdlets). The folder Client provides the cmdlet to perform the environment configuration like

Set-Configuration -BaseUrl "https://petstore.com" -Cookies "xyxxxxxxx"

src folder contains the .psd1 and .psm1 files.

tests:- tests folder contains the Pester test for Api and Model folder. it provides the place holder user needs to add the specific test case based on the cmdlet behaviour.

Using the PowerShell SDK

After running the Build.ps1 script, import the module and follow the below steps to connect to the remote server and use the generated cmdlets.

PS c:/> Import-Module -Name .\src\PSPetstore
#Verify the module is imported by following cmdlet.
PS C:/> Get-Module

ModuleType Version    Name         ExportedCommands
---------- -------    ----         ----------------
Script     1.0.2      PSPetstore    {Add-PSPet, ConvertFrom-PSJsonToApiResponse, ConvertFrom-PSJsonToCategory, ConvertFrom-PSJsonToInlineObject…}
#Configure the url and Auth configuration
PS C:/> Set-PSConfiguration -BaseUrl "https://petstore.xyz.com" -cookie 'Token="jgjgcjshdchdsgcjsdhgc"'
Once the the url and Auth configuration is done user can verify the same by using the cmdlet 
PS C:/> Get-PSConfiguration
Name                           Value
----                           -----
Username
ApiKeyPrefix                   {}
Cookie                         Token="jgjgcjshdchdsgcjsdhgc" 
BaseUrl                        http://petstore.xyz.com
AccessToken
DefaultHeaders                 {}
ApiKey                         {}
Password
SkipCertificateCheck           False

Happy learning :-)

For more about OpenAPI refer to https://www.openapis.org/