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/[email protected]
+        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/[email protected]
@@ -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/[email protected]
@@ -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
 

www/apps/api-reference/components/Tags/Operation/DescriptionSection/Responses/index.tsx

@@ -18,11 +18,12 @@ const TagsOperationDescriptionSectionResponses = ({
         className={clsx("[&>details:not(:first-of-type)>summary]:border-t-0")}
       >
         {Object.entries(responses).map(([code, response], index) => {
+          const successCode = code.startsWith("20")
           return (
             <Fragment key={index}>
               {response.content && (
                 <>
-                  {(code === "200" || code === "201") && (
+                  {successCode && (
                     <>
                       <DetailsSummary
                         title={`${code} ${response.description}`}
@@ -43,7 +44,7 @@ const TagsOperationDescriptionSectionResponses = ({
                       />
                     </>
                   )}
-                  {code !== "200" && code !== "201" && (
+                  {!successCode && (
                     <Details
                       summaryElm={
                         <DetailsSummary
@@ -72,12 +73,8 @@ const TagsOperationDescriptionSectionResponses = ({
                   title={`${code} ${response.description}`}
                   subtitle={"Empty response"}
                   badge={
-                    <Badge
-                      variant={
-                        code === "200" || code === "201" ? "green" : "red"
-                      }
-                    >
-                      {code === "200" || code === "201" ? "Success" : "Error"}
+                    <Badge variant={successCode ? "green" : "red"}>
+                      {successCode ? "Success" : "Error"}
                     </Badge>
                   }
                   expandable={false}

www/apps/api-reference/package.json

@@ -59,6 +59,6 @@
     "types": "*"
   },
   "engines": {
-    "node": ">=18.17.0"
+    "node": ">=20"
   }
 }