Upgrade to Pro — share decks privately, control downloads, hide ads and more …

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

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.

Ee25768ac97f432a851489f5168ac010?s=128

William Cheng

May 13, 2021
Tweet

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