From zero to publishing PowerShell API clients in PowerShell Gallery within minutes.

Do you want to access REST APIs using PowerShell with ease? With OpenAPI Generator, you can auto-generate a PowerShell module given an OpenAPI specification and then publish the module to PowerShell Gallery within minutes. In this talk, I'll walk you through the code generation process in 3 steps.

Using PowerShell to obtain data via REST(ful) APIs is not an uncommon task. Instead of using Invoke-RestMethod or Invoke-WebRequest to manually build the HTTP call, is there any other approach we can provide a better experience to PowerShell users?

OpenAPI Generator, an open-source project used by IBM, Cisco, RedHat, and many more companies in production, offers an easy way to generate high-quality API clients in 30+ programming languages including PowerShell. All it needs is an OpenAPI specification describing the REST APIs and within minutes, it can generate a fully-functional PowerShell module with documentation, sample codes, and test templates.

In this talk, we will walk through an example of generating a PowerShell module and then publishing it to PowerShell Gallery in only steps. We will explain the fundamentals such as OpenAPI specification, OpenAPI Generator, and the core of the PowerShell module. Then we'll also touch on customizing the PowerShell clients to meet your unique requirements.

Transcript

1. #PSHSummit From zero to publishing PowerShell API clients in PowerShell Gallery within minutes. William Cheng @wing328
2. #PSHSummit Agenda - What's OpenAPI Generator? - How to generate PowerShell modules using OpenAPI Generator? (Demo) 2
3. #PSHSummit William Cheng • #1 contributor to OpenAPI Generator • Core team, founding member of OpenAPI Generator (https://openapi-generator.tech) • eBook author: https://gumroad.com/wing328 • Conference speaker: https://speakerdeck.com/wing328/ • Founder of RESTUnited.com • Morgan Stanley Alumni • Github, Twitter: @wing328 3
4. #PSHSummit What is OpenAPI Generator? 4 [OUTPUT] API clients, server stubs, documentation etc • API clients (30 programming languages) • 30+ server frameworks • API Documentations • GraphQL, Protobuf, Avro schemas • Apache2 web server config • MySQL DB schemas [INPUT] OpenAPI Spec (YAML/JSON) For REST APIs • Swagger 1.2 • Swagger/OpenAPI 2.x • OpenAPI 3.x [PROCESS] OpenAPI Generator • Java package (JAR) • CLI • Brew (MacOS) • REST API • Docker • npm package wrapper (~120k weekly download) • Plug-ins (Maven, Gradle, Bazel, etc) • IDE integrations (Eclipse, IntelliJ IDEA, VS Code, etc)
5. #PSHSummit Who are using OpenAPI Generator in production?
6. #PSHSummit Demo 1. Generate PS module for Pet Store API (https://pubi.org/petstore_oas3.json) 2. Customize the output 3. Make some API calls! 4. Add integration tests 5. Publish the modules to PowerShell Gallery (https://www.powershellgallery.com/)
7. #PSHSummit Generate PS module for Pet Store API - OpenAPI spec: https://pubi.org/petstore_oas3.json - Command: $ openapi-generator-cli generate -g powershell -i https://pubi.org/petstore_oas3.yaml -o ./demo
8. #PSHSummit Review the output
9. #PSHSummit Customization - List of generator options $ openapi-generator-cli config-help -g powershell - Command to customize the version and package name: $ openapi-generator-cli generate -g powershell -i https://pubi.org/petstore_oas3.yaml -o ./demo2 --additional-properties packageName=PSPetstoreDemo,packageVersion=0.3.4
10. #PSHSummit Customization - Customize the Mustache templates (modules/openapi-generator/src/main/resources/powershell/) - Command to customize the version and package name: $ git clone https://github.com/openAPITools/openapi-generator/ $ cp -R openapi-generator/modules/openapi-generator/src/main/resources/p owershell/ custom_template $ openapi-generator-cli generate -g powershell -i https://pubi.org/petstore_oas3.yaml -o ./demo4 -t custom_template
11. #PSHSummit Installation - Command to customize the version and package name: $ openapi-generator-cli generate -g powershell -i https://pubi.org/petstore_oas3.yaml -o ./demo6 --additional-properties packageName=PSPetstoreDemo,packageVersion=0.3.4
12. #PSHSummit Tests - Test file to add tests: ./tests/Api/PetApi.Tests.ps - Add a Pet and then get a Pet to check the values
13. #PSHSummit Appveyor - Command to customize the powershell version as well: $ openapi-generator-cli generate -g powershell -i https://pubi.org/petstore_oas3.yaml -o ./demo6 --additional-properties packageName=PSPetstoreDemo,packageVersion=0.3.4,powershell Version=5.0
14. #PSHSummit In summary ... 1. One single OpenAPI Generator command to generate the PowerShell module 2. Push the code to Github 3. Enable AppVeyor with PowerShell Gallery API key 4. Release!
15. #PSHSummit Contribute Back - Contribute back enhancements, bug fixes - Donation https://opencollective.com/openapi_generator 🙏
16. #PSHSummit eBook - OpenAPI Generator for PowerShell Developers https://gum.co/openapi_generator_powershell
17. #PSHSummit Q&A - Contact: wing328hk@gmail.com