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:

1. ApiDoc:

   cd ~/Projects
   git clone [email protected]:Chub-Engineering/ApiDoc.git
   cd ApiDoc
   git pull origin main
   npm install

2. apiservicev3:

   cd ~/Projects
   git clone [email protected]:Chub-Engineering/apiservicev3.git
   cd apiservicev3
   git pull origin main
   npm install

3. integrations:

   cd ~/Projects
   git clone [email protected]: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

1. Update the schemas:

    cd ~/Projects/ApiDoc
    node generate-v3-schema.js

2. Generate typescript types.

   Link to Documentation: ts-generator

3. 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>

4. Create new apiservicev3 PR based on <branch-name> branch.

Validation Rules

1. Update the validation rules:

   cd ~/Projects/ApiDoc
   node generate-friendly-rules.js

2. 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>

3. 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