[REQ][PowerShell] Improve generated PowerShell examples
Created by: SimeonGerginov
Is your feature request related to a problem? Please describe.
Currently PowerShell
examples can be used in the mustache templates
through the x-powershell-example
vendor extension. This is very useful for generating and showing an example for a specific cmdlet. However there're a few issues with the current approach:
- Currently
Models
are nested inside the generated example which could result in the following code:
Invoke-Api -Model1 (Initialize-Model1 -Model2 (Initialize-Model2 -Model3 (Initialize-Model3)))
- Enums are generated through
Initialize-*
cmdlets. - Maps which in
PowerShell
are hashtables are not covered in the examples. - Currently all parameters are generated in the examples regardless if they're required or optional. For larger specs, this results in a very long and hard to read example.
Describe the solution you'd like
I would suggest refactoring the example code and addressing the issues listed above: Model
initialization can occur before the Invoke-*
call which would result in a more readable example. Also adding support for Enums and Maps will definetely improve the example. And lastly, adding an additional vendor extension like x-powershell-example-required
could only generate examples with required parameters. This way the consumer can choose in the templates on whether to receive the full example or the minimal one that is needed to invoke an API Operation
.
Describe alternatives you've considered
Additional context
I'd be happy to contribute the improved example structure for PowerShell
.