docs: general fixes and improvements (#7918)

* docs improvements and changes

* updated module definition

* modules + dml changes

* fix build

* fix vale error

* fix lint errors

* fixes to stripe docs

* fix condition

* fix condition

* fix module defintion

* fix checkout

* disable UI action

* change oas preview action

* flatten provider module options

* fix lint errors

* add module link docs

* pr comments fixes

* fix vale error

* change node engine version

* links -> linkable

* add note about database name

* small fixes

* link fixes

* fix response code in api reference

* added migrations step

.github/workflows/generate-preview-references.yml

@@ -6,5 +6,60 @@ on:
 jobs:
   preview-references:
     uses: ./.github/workflows/generate-resources-reference.yml
-  preview-api-ui:
-    uses: ./.github/workflows/generate-public-references.yml
+  preview-api:
+    name: Generate OAS
+    runs-on: ubuntu-latest
+    steps:
+      - name: Cancel Previous Runs
+        uses: styfle/cancel-workflow-action@0.11.0
+        with:
+          access_token: ${{ github.token }}
+
+      - name: Checkout
+        uses: actions/checkout@v3
+        with:
+          fetch-depth: 0
+
+      - name: Setup Node.js environment
+        uses: actions/setup-node@v3
+        with:
+          node-version: 20
+          cache: "yarn"
+
+      - name: Install dependencies
+        uses: ./.github/actions/cache-deps
+        with:
+          extension: reference
+
+      - name: Build Packages
+        run: yarn build
+
+      - name: Install www/utils Dependencies
+        run: yarn
+        working-directory: www/utils
+
+      - name: Build www/utils packages
+        run: yarn build
+        working-directory: www/utils
+
+      - name: Run docblock generator
+        run: "yarn generate:oas"
+        working-directory: www/utils
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          GIT_OWNER: ${{ github.repository_owner }}
+          GIT_REPO: medusa
+
+      - name: Generate API Reference (v2)
+        run: yarn openapi:generate
+
+      - name: Create Pull Request
+        uses: peter-evans/create-pull-request@v4
+        with:
+          commit-message: "chore(docs): Generated API Reference (v2)"
+          base: "develop"
+          title: "chore(docs): Updated API Reference (v2)"
+          labels: "type: chore"
+          add-paths: www/apps/api-reference/specs
+          branch: "docs/generate-api-ref"
+          branch-suffix: "timestamp"

.github/workflows/generate-public-references.yml

@@ -1,6 +1,5 @@
 name: Generate Public References
 on:
-  workflow_call:
   workflow_dispatch:
     inputs:
       referenceName:
@@ -13,7 +12,7 @@ on:
 jobs:
   api-v2:
     runs-on: ubuntu-latest
-    if: ${{ github.event_name == 'release' || github.event_name == 'schedule' || github.event.inputs.referenceName == 'all' || github.event.inputs.referenceName == 'api' }}
+    if: ${{ github.event_name == 'release' || github.event_name == 'workflow_dispatch' || github.event.inputs.referenceName == 'all' || github.event.inputs.referenceName == 'api' }}
     steps:
       - name: Cancel Previous Runs
         uses: styfle/cancel-workflow-action@0.11.0
@@ -23,7 +22,6 @@ jobs:
       - name: Checkout
         uses: actions/checkout@v3
         with:
-          token: ${{ secrets.REFERENCE_PAT }}
           fetch-depth: 0
 
       - name: Setup Node.js environment
@@ -63,7 +61,7 @@ jobs:
           branch-suffix: "timestamp"
   ui:
     runs-on: ubuntu-latest
-    if: ${{ github.event_name == 'release' || github.event_name == 'schedule' || github.event.inputs.referenceName == 'all' || github.event.inputs.referenceName == 'ui' }}
+    if: ${{ github.event_name == 'release' || github.event_name == 'workflow_dispatch' || github.event.inputs.referenceName == 'all' || github.event.inputs.referenceName == 'ui' }}
     steps:
       - name: Cancel Previous Runs
         uses: styfle/cancel-workflow-action@0.11.0
@@ -73,7 +71,6 @@ jobs:
       - name: Checkout
         uses: actions/checkout@v3
         with:
-          token: ${{ secrets.REFERENCE_PAT }}
           fetch-depth: 0
 
       - name: Setup Node.js environment

.github/workflows/generate-resources-reference.yml

@@ -60,12 +60,12 @@ jobs:
         working-directory: www/utils
 
       - name: Generate References
-        if: ${{ github.event_name == 'workflow_dispatch' || github.event_name == 'schedule' }}
-        run: "yarn start generate ${{ github.event.inputs.referenceName }} --merge"
+        if: ${{ github.event_name == 'workflow_dispatch' }}
+        run: "yarn start generate ${{ github.event.inputs.referenceName || 'all' }} --merge"
         working-directory: www/utils/packages/typedoc-generate-references
 
       - name: Generate References
-        if: ${{ github.event_name != 'workflow_dispatch' || github.event_name == 'schedule' }}
+        if: ${{ github.event_name != 'workflow_dispatch' }}
         run: "yarn generate:references"
         working-directory: www/utils