跳至主要内容

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

标签

标签：

评论

发表评论

此博客中的热门博文

Use MobaDiff with git difftool

Recently there's an activity in IT that forces the deletion of all unauthorized softwares from all work machines. Unfortunately, kdiff3 is one in the list. As it is generally okay to use vimdiff as an alternative for kdiff3, A gui tool is better suited for desktop workflows. Known that MobaXterm is shipping a gui diff tool named MobaDiff. But it only appears in the windows right click context menu. Find the real application name takes me some time to search in the windows registry. "MobaRTE.exe", which is the one invoked by HKCR\*\shell\MobaDiff. And it was invoked with "-contextdiff" switch to show MobaDiff UI, while when the switch is "-contextedit" it shows MobaTextEditor. Too bad that the "-contextdiff" switch do not support pre-image post-image as other diff tool did, which effectively made it unable to be used as a command line diff utility. Also MobaTech did not mention anything in their document of this Mob...
发表评论
阅读全文

Winget: From Quirky Underdog to Stable Champion

Remember winget, the Windows Package Manager that started as a playful experiment? Well, prepare to be surprised – it's grown into a powerful and highly stable tool for managing your software, including in environments with network restrictions . Gone are the days of unreliable installs and limited functionality. The developers have diligently transformed winget into a reliable contender in the package manager arena. Updates arrive regularly, bringing stability, enhanced features, and wider app support . Here's why you should give winget another look: Unified experience: Manage all your apps from a single command line , ditching the scattered hunt for individual installers and downloads. Security focus: Winget verifies package integrity and signatures, ensuring you get authentic and secure software . Efficiency: Say goodbye to manual downloads and updates. Winget automates the process, saving you time and effort. Customization: Configure installation options and choose s...
发表评论
阅读全文

Eglot and before/after-save-hook and use-package

In Emacs, when you try to automate some actions during every save action, you will surely get to the before-save-hook and the after-save-hook. Simply adding something like gofmt-before-save to before-save-hook will save you tons of time to do the go-fmt. And then, I meet eglot, and gopls will also save me tons of time doing googling and api documentation navigation. But eglot-ensure is not very friendly to the good old ways of how after-save-hooks were designed to work. It makes the before/after-save-hook a buffer local variable and it does not inherit the variable's global value. So, to make before/after-save-hook work again, experts start to adding hooks to major mode specific hooks like this: emacs.md - Go (opensource.google) """ ;; Optional: install eglot-format-buffer as a save hook. ;; The depth of -10 places this before eglot's willSave notification, ;; so that that notification reports the actual contents that will be saved. (defu...
发表评论
阅读全文