My openapi workflow

The workflow I am trying to work with

Recently, I was working on bring openapi to my workflow to minimize the API related effort on Restful project.

My goal was to using openapi generator to generate client and server interface stubs. Then using this generated code as SDK in both frontend and backend so that I will not have to deal with HTTP and the restful details.

My Goal

1. No more restful coding
2. API spec to code auto generation
3. Minimized code maintenance effort
4. Generate client and server code from same spec
5. Multiple languages and framework support, vue, pure js, springboot, springboot-jersy
6. Easy to regenerate at anytime.

My project structure

It feels like openapi-generator-cli fit my needs very well.

At present, I only have one API spec file, So I just named it 'openapi.yaml'.

In the future, if it requires me to split my openapi spec, I'll put them into a subdirectory named 'openapi'. As the openapi-generator-cli has a configuration parameter (with jsonpath $.generator-cli.generators.glob in 'openapitools.json' file)that enables me to selectively choose a subset of my specs to work with.

Then, as I need all my client and server code generated from the same set of spec file/s. I will define each generator in wrapper configuration, namely openapitools.json , with its own set of generator specific configuration.

{
  "$schema": "node_modules/@openapitools/openapi-generator-cli/config.schema.json",
  "spaces": 2,
  "generator-cli": {
    "version": "5.3.0",
    "generators": {
      "vue-client": {
        "generatorName": "typescript-axios",
        "output": "#{cwd}/vue-client",
        "glob": "openapi.yaml",
        "additionalProperties": {
          "npmName": "practiceGitAgentVue",
          "npmRepository": "http://192.168.1.100/repositories/npm-private"
        }
      },
      "js-client": {
        "generatorName": "javascript",
        "output": "#{cwd}/js-client",
        "glob": "openapi.yaml",
        "additionalProperties": {
          "npmName": "practiceGitAgentJs",
          "npmRepository": "http://192.168.1.100/repositories/npm-private"
        }
      },
      "java-client": {
        "generatorName": "java",
        "output": "#{cwd}/java-client",
        "glob": "openapi.yaml",
        "additionalProperties": {
          "apiPackage": "com.openapi.practice.api",
          "artifactId": "git-agent-java-client",
          "artifactUrl": "https://foo.bar.ml/fktpp/git-agent-api",
          "scmDeveloperConnection": "https://foo.bar.ml/fktpp/git-agent-api.git",
          "scmUrl": "https://foo.bar.ml/fktpp/git-agent-api",
          "dateLibrary": "java8",
          "developerEmail": "fktpp@foo.bar.com",
          "developerName": "It's me FKtPp ;)",
          "developerOrganization": "foo.bar.com",
          "developerOrganizationUrl": "http://www.foo.bar.com",
          "groupId": "com.openapi.practice",
          "library": "webclient",
          "modelPackage": "com.openapi.practice.model",
          "basePackage": "com.openapi.practice",
          "snapshotVersion": true,
          "parentGroupId": "org.springframework.boot",
          "parentArtifactId": "spring-boot-starter-parent",
          "parentVersion": "2.3.12.RELEASE"
        }
      },
      "spring-server": {
        "generatorName": "spring",
        "output": "#{cwd}/spring-server",
        "glob": "openapi.yaml",
        "additionalProperties": {
          "apiPackage": "com.openapi.practice.api",
          "artifactId": "git-agent-spring-server",
          "artifactUrl": "https://foo.bar.ml/fktpp/git-agent-api",
          "scmDeveloperConnection": "https://foo.bar.ml/fktpp/git-agent-api.git",
          "scmUrl": "https://foo.bar.ml/fktpp/git-agent-api",
          "dateLibrary": "java8",
          "developerEmail": "fktpp@foo.bar.com",
          "developerName": "FKtPp",
          "developerOrganization": "foo.bar.com",
          "developerOrganizationUrl": "http://www.foo.bar.com",
          "groupId": "com.openapi.practice",
          "modelPackage": "com.openapi.practice.model",
          "basePackage": "com.openapi.practice",
          "snapshotVersion": true,
          "parentGroupId": "org.springframework.boot",
          "parentArtifactId": "spring-boot-starter-parent",
          "parentVersion": "2.3.12.RELEASE"
        }
      },
      "jersy-server": {
        "generatorName": "jaxrs-jersey",
        "output": "#{cwd}/jersy-server",
        "glob": "openapi.yaml",
        "additionalProperties": {
          "apiPackage": "com.openapi.practice.api",
          "artifactId": "git-agent-jersy-server",
          "artifactUrl": "https://foo.bar.ml/fktpp/git-agent-api",
          "scmDeveloperConnection": "https://foo.bar.ml/fktpp/git-agent-api.git",
          "scmUrl": "https://foo.bar.ml/fktpp/git-agent-api",
          "dateLibrary": "java8",
          "developerEmail": "fktpp@foo.bar.com",
          "developerName": "FKtPp",
          "developerOrganization": "foo.bar.com",
          "developerOrganizationUrl": "http://www.foo.bar.com",
          "groupId": "com.openapi.practice",
          "modelPackage": "com.openapi.practice.model",
          "basePackage": "com.openapi.practice",
          "snapshotVersion": true,
          "parentGroupId": "org.springframework.boot",
          "parentArtifactId": "spring-boot-starter-parent",
          "parentVersion": "2.3.12.RELEASE"
        }
      }
    }
  }
}

Later on, I will be able to generate all my API stub code by just run openapi-generator-cli's generate action without any special parameters.

openapi-generator-cli generate

• directory structure
  

  ├─java-client
  │  ├─.openapi-generator
  │  ├─api
  │  ├─docs
  │  ├─gradle
  │  │  └─wrapper
  │  └─src
  │      ├─main
  │      │  └─java
  │      │      └─com
  │      │          └─openapi
  │      │              └─practice
  │      │                  ├─api
  │      │                  ├─auth
  │      │                  └─model
  │      └─test
  │          └─java
  │              └─com
  │                  └─openapi
  │                      └─practice
  │                          ├─api
  │                          └─model
  ├─jersy-server
  │  ├─.openapi-generator
  │  └─src
  │      ├─gen
  │      │  └─java
  │      │      └─com
  │      │          └─openapi
  │      │              └─practice
  │      │                  ├─api
  │      │                  └─model
  │      └─main
  │          ├─java
  │          │  └─com
  │          │      └─openapi
  │          │          └─practice
  │          │              └─api
  │          │                  ├─factories
  │          │                  └─impl
  │          └─webapp
  │              └─WEB-INF
  ├─js-client
  │  ├─.openapi-generator
  │  ├─docs
  │  ├─src
  │  │  ├─api
  │  │  └─model
  │  └─test
  │      ├─api
  │      └─model
  ├─spring-server
  │  ├─.openapi-generator
  │  └─src
  │      └─main
  │          ├─java
  │          │  ├─com
  │          │  │  └─openapi
  │          │  │      └─practice
  │          │  │          ├─api
  │          │  │          └─model
  │          │  └─org
  │          │      └─openapitools
  │          │          └─configuration
  │          └─resources
  └─vue-client
      └─.openapi-generator