OpenApi Generator Runner Initial Proposal

OpenApi Generator Runner Initial Proposal.md

OpenApi Generator Runner

Motivation

openapi-generator offers 50+ clients, but very often those clients don't work "out of the box" with a real-life OpenApi specification. Often one has to use template customization or custom commands and options to make the clients work. In drastic cases, a user may have to even add plugins to the generator. Furthermore, once the generator is designed, the user is obligated to test the client code with real use cases, which often involves writing a lot of custom code per client. This can become quite a management challenge - and in my case has prompted the development of a tool that can download the openapi, generate the clients in a folder nearby sometimes using templates to customize the authentication process, and test the result. Setting up this process has been a surprisingly long and arduous process, and I can only imagine that others have found themselves in a similar situation.

Proposal

I'd like to build an openapi-generator-runner that can read an x-open-api-generator extension object within the openapi specification that describes all the supported clients, the supported version of openapi-generator, details of how to build each client, how to test it, and how to publish it. This way, companies that want to publish their own clients that are guaranteed to work can do so with confidence and without writing a lot of duplicated code.

Proposed Methodology

The x-open-api-generator extension could look like:

{
  "open-api-generator": {
    "version": "5.3.1"
  }
  "generators": {
    "<generator-name>": {
      "generate": {
        "templates": {
          "<file-name>": "<file-string>",
          "<dir-name>": {
            "<file-name>": "<file-string>"
          }
        },
        "options": {
          "<my-option-key>": "<my-option-value>"
        },
        "directory": "<github-url>"
      },
      "install": {
        "script": ["<command>"]
      },
      "test": {
        "script": ["<command>"]
      },
      "deploy": {
        "github": "<github-url>"
      }
    }
  }
}

For instance, the Python client might be described with:

{
  "generators": {
    "python": {
      "generate": {
        "templates": {
          "README.mustache": "Welcome!"
        },
        "options": {
          "packageName": "myPackage"
        },
        "directory": "https://github.com/myaccount/mypythonclient.git"
      },
      "install": {
        "script": ["pipenv install . --dev"]
      },
      "test": {
        "script": ["pipenv run pytest -n 8"]
      },
      "deploy": {
        "github": "https://github.com/myaccount/mypythonclient.git"
      }
    }
  }
}

Which would translate to the following steps:

1. Setup the templates dir.
2. Download the GitHub repo to a specified directory
3. Run the newest openapi-generator against the current specifications with the templates and the options specified.
4. Run the install script to install the generator.
5. Run the test script. If it passes, proceed. Otherwise report for errors for this client and move on to the next.
6. Run the deploy script. In this case pushing back to the same GitHub repo and tagging with the correct version.
7. Continue to the next specified generator and repeat steps 1-7 until all generators are processed.

This is just an initial extension schema proposal that could be extended to add functionality that would support many different deployments, testing strategies, etc. The main goal would be to provide an open source repo that could dramatically reduce management code needed to effectively use opneapi-generator.