Orquesta workflow API documentor to Swagger OAS definition?

willowhawk · August 3, 2021, 7:38pm

I’m looking to created standardized OAS v2 or v3 YAML to give to consumers of my workflows, such that they can import them into Insomnia, Postman, or other API client tools, or even just visualize in SwaggerHub.

I know I can get a JSON blob of a particular action by going through the API endpoint using an api key or token, but that isn’t quite sufficient for what I’m looking for.

I see that there is an OpenAPI generator for the main ST2 api created during the build process.

Has anyone successfully adapted it to do “documentation-by-code” or something similar that I can feed it my Orquesta actions and it will make a nice little OAS YAML file?

blag · August 3, 2021, 8:03pm

I’m not 100% sure what you’re asking for, and I’m not familiar with OAS, so I don’t know if I will be of any help.

AFAIK, Orquesta itself doesn’t have an HTTP API. ST2 has an HTTP API, as you’ve found:

github.com

StackStorm/st2/blob/master/st2common/st2common/openapi.yaml

# NOTE: This file is auto-generated - DO NOT EDIT MANUALLY
# Edit st2common/st2common/openapi.yaml.j2 and then run
# make .generate-api-spec
# to generate the final spec file
swagger: '2.0'

info:
  version: "1.0.0"
  title: StackStorm API
  description: |
    
    ## Welcome

    Welcome to the StackStorm API Reference documentation! You can use the StackStorm API to integrate StackStorm with 3rd-party systems and custom applications. Example integrations include writing your own self-service user portal, or integrating with other orquestation systems.

    This document provides an overview of how to use the API. Use the menu on the left to look up details of specific API endpoints. For more information about how StackStorm works, and how to use it, check out the main [StackStorm documentation](https://docs.stackstorm.com).

    > ### A Quick Note
    > This API is intended for software developers, and those are who are comfortable working with RESTful APIs, and writing some code. You do not need to use this API to work with StackStorm, or to use and write integration packs for StackStorm.

This file has been truncated. show original

Are you trying to get an OAS YAML API description of ST2 actions for a particular pack?

willowhawk · August 4, 2021, 3:27pm

Yes, more specifically I’m seeking if anyone has already written a tool that scans your Orquesta workflow YAML to identify the input parameters and the output schema to create an OpenAPI compliant definition. I know that ST2’s built in API allows a JSON formatted version of this, but it’s not compatible with OpenAPI without conversion of some kind. Thought I’d ask before I go about writing one.