Gitter | AppVeyor (Windows) |
---|---|
A PowerShell module with commands to generate the PowerShell commands for a given RESTful Web Services using Swagger/OpenAPI documents.
Usage | Platforms |
---|---|
Developer | Windows, PowerShell 5.1+, Latest PowerShell Core |
Module Publisher | PowerShell 5.1+ |
Module Consumer | PowerShell 5.1+, Latest PowerShell Core |
Future note: We plan on supporting PowerShell 4+ for module consumers in the future; that scenario is untested currently. Testing note: While any full PowerShell version is fine for development, we recommend using PowerShell 5.1+ to enable testing our implementation of Get-FileHash.
Dependency | Version | Description |
---|---|---|
AutoRest | 0.17.3 or newer | Tool to generate C# SDK from Swagger spec |
CSC.exe (Microsoft.Net.Compilers) | 2.3.1 or newer | C# Compiler to generate C# SDK assembly on Windows PowerShell |
Newtonsoft.Json | Full CLR: 6.0.8, Core CLR: 9.0.1 | NuGet package containing Newtonsoft.Json assembly, required for all modules |
Microsoft.Rest.ClientRuntime | 2.3.4 or newer | NuGet package containing Microsoft.Rest.ClientRuntime assembly, required for all modules |
Microsoft.Rest.ClientRuntime.Azure | 3.3.4 or newer | NuGet package containing Microsoft.Rest.ClientRuntime.Azure assembly, required for Microsoft Azure modules |
AzureRM.Profile | 2.0.0 or newer | Module containing authentication helpers, required for Microsoft Azure modules on PowerShell |
AzureRM.Profile.NetCore.Preview | * | Module containing authentication helpers, required for Microsoft Azure modules on PowerShell Core |
NOTE: In the short term, for best performance, the operation IDs in your Open API specifications should be of the form "_". For example, the operation ID "Resource_GetByName" gets a resource named Resource by name.
-
Get PSSwagger!
- Install from PowerShellGallery.com
Install-Module -Name PSSwagger
- Clone the repository
git clone https://github.com/PowerShell/PSSwagger.git
- Install from PowerShellGallery.com
-
Ensure AutoRest is installed and available in $env:PATH
- Follow the instructions provided at AutoRest github repository.
- Ensure AutoRest.cmd path is in $env:Path
$env:path += ";$env:APPDATA\npm" Get-Command -Name AutoRest
-
Ensure CSC.exe is installed and available in $env:PATH
- If CSC.exe is not installed already, install Microsoft.Net.Compilers package
Install-Package -Name Microsoft.Net.Compilers -Source https://www.nuget.org/api/v2 -Scope CurrentUser
- Add CSC.exe path to $env:Path
$package = Get-Package -Name Microsoft.Net.Compilers $env:path += ";$(Split-Path $package.Source -Parent)\tools" Get-Command -Name CSC.exe
- If CSC.exe is not installed already, install Microsoft.Net.Compilers package
-
If you plan on pre-compiling the generated assembly, ensure you have the module AzureRM.Profile or AzureRM.NetCore.Preview available to PackageManagement if you are on PowerShell or PowerShell Core, respectively.
-
Run the following in a PowerShell console from the directory where you cloned PSSwagger in
# Import PSSwagger module Import-Module PSSwagger # If you are trying from a clone of this repository, follow below steps to import the PSSwagger module. # Ensure PSSwaggerUtility module is available in $env:PSModulePath # Please note the trialing back slash ('\') to ensure PSSwaggerUtility module is available. $PSSwaggerFolderPath = Resolve-Path '.\PSSwagger\' $env:PSModulePath = "$PSSwaggerFolderPath;$env:PSModulePath" Import-Module .\PSSwagger # Ensure PSSwagger module is loaded into the current session Get-Module PSSwagger # Prepare input parameters for cmdlet generation $null = New-Item -ItemType Directory -Path C:\GeneratedModules -Force $params = @{ # Download the Open API v2 Specification from this location SpecificationUri = 'https://raw.githubusercontent.com/Azure/azure-rest-api-specs/master/arm-batch/2015-12-01/swagger/BatchManagement.json' # Output the generated module to this path Path = 'C:\GeneratedModules\' # Name of the generated module Name = 'AzBatchManagement' # This specification is for a Microsoft Azure service, so use Azure-specific functionality UseAzureCsharpGenerator = $true } # You may be prompted to download missing dependencies New-PSSwaggerModule @params
The generated module will be in the
C:\Temp\GeneratedModule\Generated.AzureRM.BatchManagement
folder. For more New-PSSwaggerModule options, check out the documentation. -
Your generated module is now ready! For production modules (i.e. modules you will publish to PowerShellGallery.com), we recommend using the -IncludeCoreFxAssembly option to generate the Core CLR assembly, strong name signing assemblies in the generated module, and authenticode signing the module. Optionally, you can remove the generated C# code (under the Generated.CSharp folder) for even more security.
There are many cases where module generation doesn't result in the most optimal names for things like parameters or commands. To enable this and many other customization options, we've introduced additional PowerShell-specific Open API extensions that can be specified separately from your main specification. For more information, check out PowerShell Extensions and New-PSSwaggerMetadataFile.
When importing the module for the first time, the packaged C# files will be automatically compiled if the expected assembly doesn't exist.
To enable Microsoft.Rest.ServiceClientTracing support, pass -Debug into any generated command.
The included PowerShell tracer uses Write-Debug to write tracing messages.
When the module is imported to older version of PowerShell, the following steps will need to be taken:
- Implement either Microsoft.PowerShell.Commands.PSSwagger.PSSwaggerClientTracing or Microsoft.Rest.IServiceClientTracingInterceptor
- Call: [Microsoft.Rest.ServiceClientTracing]::AddTracingInterceptor($myTracer)
- If you use the Verbose or Debug streams of PowerShell, set $VerbosePreference or $DebugPreference, respectively
Note 1: We're not sure why yet, but something is setting [Microsoft.Rest.ServiceClientTracing]::IsEnabled to true before all cmdlet calls
If the module's full CLR assembly is precompiled, the symbols folder will contain:
- Generated.cs - The C# code used to generate the assembly
- *.pdb - The corresponding PDB file that defines Generated.cs as the source file
When the "x-ms-pageable" extension is specified in the Swagger spec, paging is enabled in the generated module. This is true for both fragment URLs (when operationName is specified) and full URLs (when operationName is not specified).
A cmdlet that supports paging will have two additional optional parameters: -Paging: A switch parameter that specifies the cmdlet should only return the first page. To access the items, use $returnValue.Page -Page: Takes as input the last page return value and outputs the next page return value (again, to access the items, use $returnValue.Page). If the return value is null, no additional pages exist.
If -Paging is not specified and the cmdlet supports paging, the cmdlet will automatically unroll all pages. Assigning the result to a variable will result in all items being retrieved. Piping the cmdlet will result in pages being retrieved on-demand.
When dependency packages are expected to be missing, silent execution (bypassing the missing packages prompt) can be achieved by calling:
Import-Module PSSwaggerUtility
PSSwaggerUtility\Initialize-PSSwaggerDependencies -AcceptBootstrap -Azure
For Microsoft Azure modules, or:
Import-Module PSSwaggerUtility
PSSwaggerUtility\Initialize-PSSwaggerDependencies -AcceptBootstrap
For all other modules.
- Swagger Specification is at: http://swagger.io/specification/
- Azure ARM based Swagger documents at: https://github.com/Azure/azure-rest-api-specs
- AutoRest Generators: https://github.com/Azure/autorest/tree/master/src/generator
You can run tests right after cloning the repository. The test scripts should install the required packages. To run the tests, navigate to the Tests directory, then run:
.\run-tests.ps1 -TestFramework <framework> -Verbose -TestSuite <TestSuite> -TestName <TestName>
TestFramework should be one of "net452" | "netstandard1.7". If you are on Windows, you can use either net452, which uses the full CLR, or netstandard1.7, which uses the Core CLR. For Linux, Darwin, or Nano Server users, you will have to use netstandard1.7.
TestFramework defaults to net452
Use TestSuite or TestName parameters to filter by Pester Tag or test name.
The script will ensure dependencies exist on your machine, like AutoRest, node.js, npm, json-server, and dotnet CLI. Then it will run pester tests in a separate PS session and validate no tests failed.
If dotnet CLI is already in your PS session's path, and you don't need to upgrade, you can use the parameter -SkipBootstrap to skip dotnet CLI bootstrapping and save lots of time.
Scenario | Description |
---|---|
Get-InternalFileHash | Tests that Get-InternalFileHash is equivalent to Get-FileHash in PS 5.1+ |
The scenario test suite contains tests that hit actual (local) web API endpoints. The following scenarios are covered:
Scenario | Description |
---|---|
PsSwaggerTestsBasic | A very basic test of a single string-only path using get and post. |
The PSSwagger implementation of the Azure Live Test Framework protocol is currently located in this repository in a subdirectory. Once PSSwaggerUtility is published to PowerShellGallery.com, the PSSwagger.LiveTestFramework code will be moved to a separate repository. You can find the readme for the PSSwagger.LiveTestFramework module here.
This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact [email protected] with any additional questions or comments.