apidefinition v1.0.1
How does it all work together?
There's some confusion about how the ApiDoc project intersects with the rest of the system. In short, when making a change
to the ApiDoc project, it's possible that the apiservicev3
project and the integrations
project will also need to be
modified to reflect the changes made here in their schema validators.
graph TD
A[Edit ApiDoc] --> B
B[Affect V3?] --> |Yes| C
B --> |No| D
C[Branch / Checkout V3] --> E
E[run ApiDoc/generate-v3-schema.js] --> F
F[Checkin / Merge / Deploy V3] --> D
D{Affect Validation?} --> |Yes| G
D --> |No| K
G[Branch / Checkout Integrations] --> H
H[run ApiDoc/generate-friendly-rules.js] --> I
I[run Integrations/api/rules/test/GenerateJsonSchemaFromSimpleRules.js] --> J
J[Checkin / Merge / Deploy Integrations] --> K
K[Checkin / Merge / Deploy ApiDoc]
Updating schemas
Whenever any schema is updated this change needs to be reflected in apiservicev3
and integrations
projects.
Please use the following described below to do that.
Setup
Make sure you have all the required local repositories configured:
- ApiDoc:
cd ~/Projects git clone git@github.com:Chub-Engineering/ApiDoc.git cd ApiDoc git pull origin main npm install
- apiservicev3:
cd ~/Projects git clone git@github.com:Chub-Engineering/apiservicev3.git cd apiservicev3 git pull origin main npm install
- integrations:
cd ~/Projects git clone git@github.com:Chub-Engineering/integrations.git cd integrations git pull origin main
Environment variables
Configure the following environment variables:
export V3_TRANSFORM=~/Projects/apiservicev3
export APIDOC_LOCATION=~/Projects/ApiDoc
V3 API Schemas
- Update the schemas:
cd ~/Projects/ApiDoc node generate-v3-schema.js
Generate typescript types.
Link to Documentation: ts-generator
Push the changes to
<branch-name>
branch:cd ~/Projects/apiservicev3 git checkout -b <branch-name> git add src/lib/transform/* git commit -m "Updated schemas" git push origin <branch-name>
Create new apiservicev3 PR based on
<branch-name>
branch.
Validation Rules
Update the validation rules:
cd ~/Projects/ApiDoc node generate-friendly-rules.js
Update JSON schema and push the changes to
<branch-name>
branch:cd ~/Projects/integrations git checkout -b <branch-name> cd api/rules/test node GenerateJsonSchemaFromSimpleRules.js cd ~/Projects/integrations git add lib/schemas/* git commit -m "Updated schemas" git push origin <branch-name>
Create new integrations PR based on
<branch-name>
branch.
Deployment
Once your code has been merged into the main branch, a GitHub action named Publish
will be available.
Select it and press the Run workflow
button to the right. You can then choose to publish to test
, staging
, or prod
.
Build and Serve Locally
npm i
# EITHER
# this method starts a dynamic server that changes with each change you make to the source
nvm use 12 # this seems to be significant. :shrug:
npm run start
# OR
# some users have been unable to run `@redocly/openapi-cli`.
# this requires a restart for each change.
node ./index.js target=[stage]
npx serve &
# THEN
sleep 2
open http://localhost:3000/build/v3/reference/
Then open a browser to: http://localhost:3000/build/v3/reference/
Generating Rules and docs
Please reference this page https://www.notion.so/commercehub/Adding-a-field-to-the-DSCO-platform-913e57f1396f42c09dfcd54cb495b7fd