Skip to content
GitLab

[core][maven][gradle] User-defined server variable substitutions

Merged Jim Schubert requested to merge server-variable-substitution into master

PR checklist

  • Read the contribution guidelines.
  • Ran the shell script under ./bin/ to update Petstore sample so that CIs can verify the change. (For instance, only need to run ./bin/{LANG}-petstore.sh, ./bin/openapi3/{LANG}-petstore.sh if updating the {LANG} (e.g. php, ruby, python, etc) code generator or {LANG} client's mustache templates). Windows batch files can be found in .\bin\windows\. If contributing template-only or documentation-only changes which will change sample output, be sure to build the project first.
  • Filed the PR against the correct branch: master, 4.1.x, 5.0.x. Default: master.
  • Copied the technical committee to review the pull request if your PR is targeting a particular programming language.

Description of the PR

This provides an initial capability for users to define values for server variable substitutions.

Given a spec with a server URL definition such as:

{
  "openapi" : "3.0.1",
  "info" : {
    "title" : "OpenAPI Petstore",
    "description" : "This is a sample server Petstore server. For this sample, you can use the api key `special-key` to test the authorization filters.",
    "license" : {
      "name" : "Apache-2.0",
      "url" : "http://www.apache.org/licenses/LICENSE-2.0.html"
    },
    "version" : "1.0.0"
  },
  "servers" : [ {
      "url": "https://{api}.{server}/{basePath}",
      "description": "The production API server",
      "variables": {
        "api": {
          "default": "petstore",
          "description": "This is the specific API to work with."
        },
        "server": {
          "default": "swagger.io"
        },
        "basePath": {
          "default": "v2"
        }
      }
    }],
…

The default will be https://petstore.swagger.io/v2, but we can now generate with user-declared options. For example:

defaults (generates targeting https://petstore.swagger.io/v2) :

generate -g kotlin -i .bak/openapi/openapi-servers.json -o .bak/server-variables/defaults

user defined values (generates targeting https://petstore.local/api):

openapi-generator generate -g kotlin \
    -i .bak/openapi/openapi-servers.json \
    -o .bak/server-variables/ours \
    --server-variables=api=petstore,basePath=api,server=local

The results:

.bak/server-variables/user/s/m/k/o/o/c/a/UserApi.kt:28:class UserApi(basePath: kotlin.String = "https://petstore.local/api") : ApiClient(basePath) {
.bak/server-variables/user/s/m/k/o/o/c/a/PetApi.kt:29:class PetApi(basePath: kotlin.String = "https://petstore.local/api") : ApiClient(basePath) {
.bak/server-variables/user/s/m/k/o/o/c/a/StoreApi.kt:28:class StoreApi(basePath: kotlin.String = "https://petstore.local/api") : ApiClient(basePath) {
.bak/server-variables/defaults/s/m/k/o/o/c/a/UserApi.kt:28:class UserApi(basePath: kotlin.String = "https://petstore.swagger.io/v2") : ApiClient(basePath) {
.bak/server-variables/defaults/s/m/k/o/o/c/a/PetApi.kt:29:class PetApi(basePath: kotlin.String = "https://petstore.swagger.io/v2") : ApiClient(basePath) {
.bak/server-variables/defaults/s/m/k/o/o/c/a/StoreApi.kt:28:class StoreApi(basePath: kotlin.String = "https://petstore.swagger.io/v2") : ApiClient(basePath) {

The design/usage of URLPathUtils.getServerURL was a little weird (it offloads generation logic to a static utility). Rather than rewriting this, I've simply passed the overrides to it. I anticipate some URLs being missed due to the static method call, but we can address these as found. I hope to have workflows rewritten by the 5.0 release and will refactor URLPathUtils.getServerURL at some point.

cc @OpenAPITools/generator-core-team @OpenAPITools/openapi-generator-collaborators