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
   

   View Slide

2. #PSHSummit
   Agenda
   - What's OpenAPI Generator?
   - How to generate PowerShell modules using OpenAPI Generator? (Demo)
   2
   

   View Slide

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
   

   View Slide

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)
   

   View Slide

5. #PSHSummit
   Who are using OpenAPI Generator in
   production?
   

   View Slide

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/)
   

   View Slide

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
   

   View Slide

8. #PSHSummit
   Review the output
   

   View Slide

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
   

   View Slide

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
    

    View Slide

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
    

    View Slide

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
    

    View Slide

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
    

    View Slide

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!
    

    View Slide

15. #PSHSummit
    Contribute Back
    - Contribute back enhancements, bug fixes
    - Donation
    https://opencollective.com/openapi_generator 🙏
    

    View Slide

16. #PSHSummit
    eBook - OpenAPI Generator for PowerShell Developers
    https://gum.co/openapi_generator_powershell
    

    View Slide

17. #PSHSummit
    Q&A
    - Contact: wing328hk@gmail.com
    

    View Slide