Freight-posting-system-schemas NPM

Freight Posting API Schemas

This repository holds the raw OAS documents for Freight Posting APIs at DAT. The master branch should always be in sync with the Freight Posting Stoplight Project.

General Assumptions

This project assumes that any OAS documents you want to generate TS models from and dereference are located under the packages directory and contain .oas2 or .oas3 (case-insensitive) in the filename.

To simplify how the code generation processes each respective package, it assumes that the directory name underneath the packages directory matches exactly with its respective npm package name that appears after the scope prefix. (ex: packages/my-cool-api --> @dat/my-cool-api)

Generating TS models

Once you feel your OAS changes are complete the next step is to generate the corresponding TypeScript models from them. This project leverages lerna as a tool for managing monorepos, so the models for all OAS files can be generated at once by running the npm script npm run build:dist. NOTE: In order for this to work, you'll need to make sure you're version of node is 14.15.1 or higher.

Make sure you've created an access token for your Stoplight profile and set it as a system environment variable, ex:
$: export STOPLIGHT_TOKEN=<YOUR ACCESS TOKEN>

What is exported in each of the sub-packages (e.g. ./packages/freight-posting-api-schemas)

Dereferenced OAS documents
This npm package also exports dereferenced OAS documents. This is useful for some tooling which doesn't support resolving the remote references that may exist in OAS.
One example use case is being able to plug this into DAT's internal @dat/node-oas-api's exported middleware. In this case, a dereferenced spec is critical, since depending on external OAS hosting services at runtime would be undesirable.
Code Models:
This npm package exports TypeScript models that were generated from the OAS files that define the specifications of the internal system's messaging contracts. By using this library you are guaranteed to have compatible data models for use in consuming or producing messages from containers within the system. You can also become aware of changes being made to the message contracts as new versions of both the API and npm package itself are published.

Updating the versions properly

Please follow the semver guidance to decide whether to bump the OAS document's version's major, minor, or patch value.

Note: The package.json version field is independent of OAS versions. This is because any given API schemas npm package may or may not export multiple OAS documents and models which may lead to incompatibility and confusion when trying to synchronize them.

Publishing

publishing the library to npm

With the option we use for lerna to publish the packages, we only need to worry about updating the version in the package.json file to the desired value. Once the PR is approved and merged, then the CI pipeline will execute the npm run publish command, and any changed packages will be published to the npm registry under our @dat scope.

publishing spec changes to stoplight

Before copying the spec from this repo to Stoplight, it is good practice to compare first, so any "untracked" changes made in stoplight are not lost. This involves copying the spec from Stoplight's "code" view:

to your local api-schema repo. Compare the files, ensuring that there are no unexpected changes in the diff. If there are, research, reconcile with team, etc. 2. Copy the contents of the spec from this repo that you wish to override in stoplight 3. Open the freight-posting project in Stoplight Next: https://next.stoplight.io/dat-solutions/freight-posting 4. Open the spec you wish to update. It will be one of the .oas3 files under MODELING 5. Click the code tab at the top 6. Select all (or delete) and paste the spec from your local repo 7. Make sure the Valid text shows at the top 8. Click "save" (takes 2 with a confirmation)

Linting the specifications

You can lint your changes as you make them using Stoplight's spectral CLI tool.

all OAS files:

$ npm run lint

> freight-posting-api-schemas@1.0.0 lint /workspace/freight/freight-common-api-schemas
> npx spectral lint ./**.oas.{json,yml,yaml}

No results with a severity of 'error' or higher found!

a specific file:

$ npx spectral lint common-types.oas3.json
OpenAPI 3.x detected

/workspace/freight/freight-common-api-schemas/common-types.oas3.json
   1:1   warning  openapi-tags                   OpenAPI object should have non-empty `tags` array.
  35:21  warning  oas3-unused-components-schema  Potentially unused components schema has been detected.
  44:28  warning  oas3-unused-components-schema  Potentially unused components schema has been detected.
  49:20  warning  oas3-unused-components-schema  Potentially unused components schema has been detected.
  79:15  warning  oas3-unused-components-schema  Potentially unused components schema has been detected.
  97:14  warning  oas3-unused-components-schema  Potentially unused components schema has been detected.
 105:16  warning  oas3-unused-components-schema  Potentially unused components schema has been detected.
 140:15  warning  oas3-unused-components-schema  Potentially unused components schema has been detected.
 146:18  warning  oas3-unused-components-schema  Potentially unused components schema has been detected.
 151:19  warning  oas3-unused-components-schema  Potentially unused components schema has been detected.
 156:17  warning  oas3-unused-components-schema  Potentially unused components schema has been detected.

✖ 11 problems (0 errors, 11 warnings, 0 infos, 0 hints)