Canopy OpenAPI Schema

This specification serves as the one and only source of truth throughout Canopy's stack.

We use the v3.0.3 version of the OpenAPI spec.

Initial setup

1. Ensure you're on Node 16 or later: nvm install lts
2. yarn
3. The pre-commit hook will bundle, validate, generate TS and Go types, and format the code before pushing. You can run either of those individually by referring to scripts in package.json.
4. Optional: install Crunch42 extension for VSCode.

Live documentation structure

The openapi.json file is the entrypoint to the modular spec that we use for development.

Paths defined within the OpenAPI specification all contain local references to the requestBodies, responses, and schemas sections. However, these sections themselves all contain remote references, so that each request body, response, and schema definition is contained within its own file in its respective directory within this documentation.

We consolidate these modules and dereference them into one unified json file that is used for validation and deployment.

Updating the live documentation

Versioning is handled automatically by the release pipeline.

Changes made to the main branch are deployed via GitHub Actions to docs.canopyservicing.com as v2-main beta version.

When committing `main`, a pre-commit hook will build and validate the `dist/consolidated.json` file to ensure a valid API specification can be generated. In order for this commit to be successful, ensure that you are running Node 14 or later.

Changes made to the production branch will be deployed via GitHub Actions to the live documentation site as the v2 latest version.

Validation

The CI workflow validates the consolidated OpenAPI file before deploying it. Please validate your changes in one of two ways before pushing:

1. yarn validate

2. Open up the Crunch42 extension for VSCode with dist/consolidated.json in the editor and run a security audit by either clicking on the purple icon in the top right corner of the editor or opening up the launcher via Cmd-Option-P and entering "security". First option should be OpenAPI: perform security audit.

   See docs for more info.

Publish

Packages will be published to npm automatically when merged into the production branch. Versioning is automatic (by the usual major.minor.patch pattern) and will take into account the commit messages in order to choose the version of the upcoming publish:

Commit message naming rules:

1. patch / fix: fix(x): desc -> ex: "fix(arguments): Fix arguments for the new account endpoint"
2. minor / feature: feat(x): desc -> ex: "feat(new_endpoint): Add a new endpoint for a new line item type"
3. major / breaking change: BREAKING CHANGE -> ex: "BREAKING CHANGE removing /accounts/update endpoint"

Outdated manual NPM publish process

Outdated, since the Github Actions CI task will automatically publish new releases now.

1. To publish to NPM, bump package version accordingly with npm version [patch|minor|major]. See NPM CLI docs.
2. Run npm publish to publish your new version.

Versioning guidelines:

• MAJOR version when you make incompatible API changes
• MINOR version when you add functionality in a backwards compatible manner
• PATCH version when you make backwards compatible bug fixes

Type Generation

1. To include a schema for type generation, include it as a part of openapi.json["schemas"].
2. Run yarn build.