Skip to content

Latest commit

 

History

History
50 lines (30 loc) · 2.95 KB

openapi-documentation.md

File metadata and controls

50 lines (30 loc) · 2.95 KB
Raw

OpenAPI

Tooling

openapi-generator-cli

Repository

This tool is a Node wrapper around the Java JAR openapi-generator. It will download the correct version of the pinned JAR automatically and acts a proxy between the JAR and the user's commands when invoking this tool.

Maintenance

Node Wrapper

The Node wrapper is pinned in package.json under the devDependencies. For the latest version, visit the npmjs website for it.

NPM and Dependabot will likely keep this up to date.

The JAR

The JAR version is maintained by openapitools.json. For the latest version, check the GitHub Releases for the JAR.

⚠️ Unlike, the node wrapper, there is no process to keep it updated. Routinely, maintainers will need to update this pin.

Generated Packages

All the generated packages are stored in the gen/ folder. Nothing should manually change the code after generation.

Developers should run npm run openapi to generate both the frontend and backend.

Backend

npm run openapi-backend command does the following:

  • Cleans the folder
  • Uses the python-flask generator. Current additional properties are:
    • packageName=chromestatus_openapi - We generate a complete python package and this is the specified name.
  • Run pip install again. We treat this as an independent package and it is specified in the requirements.txt file.

Other notes: The generator allows you to specify generating the models only. But for the python-flask generator, it will generate an incomplete setup.py in that mode. If the setup.py is incomplete, pip install will fail. As a result, we generate everything. A future optimization would be to exclude the controller file changes via .gitignore. Once all routes are generated by OpenAPI, it would be wise to revisit using the controllers as well.

Frontend

npm run openapi-frontend command does the following:

  • Cleans the folder
  • Uses the typescript-fetch generator. Current additional properties are:
    • npmName=chromestatus-openapi - We generate a complete NPM package and this is the specified name. (That package is written in typescript and if we wanted to not use it as an independenct package, we would need typescript ourselves)
    • withInterfaces=true - Generate interfaces. Useful for when we migrate to typescript.
    • supportsES6=true - By default, it generates CommonJS ES5. That client interferes with the test framework. As a result, generate the newer es6 version.
  • Run npm install again. We treat this as an independent package and it is specified in the package.json file.