chore(docs): Refactor API Reference (medusajs#1883)

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

@@ -0,0 +1,51 @@
+name: Generate API Reference
+on: 
+  pull_request:
+    types:
+      - closed
+    branches:
+      - "master"
+    paths:
+      - packages/medusa/src/api/routes/**
+      - '!packages/medusa/src/api/routes/**/index.ts'
+      - '!packages/medusa/src/api/routes/**/index.js'
+jobs:
+  api:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Cancel Previous Runs
+        uses: styfle/cancel-workflow-action@0.9.1
+        with:
+          access_token: ${{ github.token }}
+
+      - name: Checkout
+        uses: actions/checkout@v2.3.5
+        with:
+          token: ${{ secrets.REFERENCE_PAT }}
+          fetch-depth: 0
+
+      - name: Setup Node.js environment
+        uses: actions/setup-node@v2.4.1
+        with:
+          node-version: "14"
+          cache: "yarn"
+
+      - name: Install dependencies
+        uses: ./.github/actions/cache-deps
+        with:
+          extension: reference
+
+      - name: Build Packages
+        run: yarn build
+
+      - name: Generate API Reference
+        run: yarn openapi:generate
+
+      - name: Create Pull Request
+        uses: peter-evans/create-pull-request@v4
+        with:
+          commit-message: 'chore(docs): Generated API Reference'
+          base: 'master'
+          title: 'chore(docs): Updated API Reference'
+          labels: 'type: chore'
+          add-paths: docs/api/*

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

@@ -46,8 +46,8 @@ jobs:
       - name: Create Pull Request
         uses: peter-evans/create-pull-request@v4
         with:
-          commit-message: 'docs: Generated JS Client Reference (automated)'
+          commit-message: 'chore(docs): Generated JS Client Reference (automated)'
           base: 'master'
-          title: 'docs: Generated JS Client Reference (automated)'
-          labels: 'type: docs'
+          title: 'chore(docs): Updated API Reference'
+          labels: 'type: chore'
           add-paths: docs/content/references/js-client/**

.github/workflows/generate-reference.yml

@@ -46,8 +46,8 @@ jobs:
       - name: Create Pull Request
         uses: peter-evans/create-pull-request@v4
         with:
-          commit-message: 'docs: Generated Services Reference (automated)'
+          commit-message: 'chore(docs): Generated Services Reference (automated)'
           base: 'master'
-          title: 'docs: Generated Services Reference (automated)'
-          labels: 'type: docs'
+          title: 'chore(docs): Generated Services Reference (automated)'
+          labels: 'type: chore'
           add-paths: docs/content/references/services/**

.github/workflows/oas-test.yml

@@ -0,0 +1,34 @@
+name: OAS Comments Format Validation
+on: 
+  pull_request:
+    paths:
+      - packages/medusa/src/api/routes/**
+
+jobs:
+  docs-test:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Cancel Previous Runs
+        uses: styfle/cancel-workflow-action@0.9.1
+        with:
+          access_token: ${{ github.token }}
+
+      - name: Checkout
+        uses: actions/checkout@v2.3.5
+        with:
+          fetch-depth: 0
+
+      - name: Setup Node.js environment
+        uses: actions/setup-node@v2.4.1
+        with:
+          node-version: "14"
+          cache: "yarn"
+
+      - name: Install dependencies
+        uses: ./.github/actions/cache-deps
+        with:
+          extension: oas
+
+      - name: Build OAS
+        run: |
+          yarn openapi:generate

.gitignore

@@ -20,4 +20,4 @@ lerna-debug.log
 
 .idea
 .turbo
-build/**
+build/**

docs/api/admin-spec3-base.json

@@ -3,70 +3,165 @@
   "info": {
     "version": "1.0.0",
     "title": "Medusa Admin API",
+    "description": "API reference for Medusa's Admin endpoints. All endpoints are prefixed with `/admin`.",
     "license": {
-      "name": "MIT"
+      "name": "MIT",
+      "url": "https://github.com/medusajs/medusa/blob/master/LICENSE"
     }
   },
   "tags": [
     {
       "name": "Auth",
-      "description": "Auth endpoints allows authorization of admin Users and manages their sessions."
+      "description": "Auth endpoints that allow authorization of admin Users and manages their sessions."
+    },
+    {
+      "name": "App",
+      "description": "App endpoints that allow handling apps in Medusa.",
+      "x-resourceId": "OAuth"
+    },
+    {
+      "name": "Batch Job",
+      "description": "Batch Job endpoints that allow handling batch jobs in Medusa.",
+      "x-resourceId": "batch_job"
+    },
+    {
+      "name": "Claim",
+      "description": "Claim endpoints that allow handling claims in Medusa.",
+      "x-resourceId": "claim_order"
     },
     {
       "name": "Collection",
+      "description": "Collection endpoints that allow handling collections in Medusa.",
       "x-resourceId": "product_collection"
     },
     {
       "name": "Customer",
+      "description": "Customer endpoints that allow handling customers in Medusa.",
       "x-resourceId": "customer"
     },
+    {
+      "name": "Customer Group",
+      "description": "Customer Group endpoints that allow handling customer groups in Medusa.",
+      "x-resourceId": "customer_group"
+    },
     {
       "name": "Discount",
+      "description": "Discount endpoints that allow handling discounts in Medusa.",
       "x-resourceId": "discount"
     },
+    {
+      "name": "Discount Condition",
+      "description": "Discount Condition endpoints that allow handling discount conditions in Medusa.",
+      "x-resourceId": "discount_condition"
+    },
+    {
+      "name": "Draft Order",
+      "description": "Draft Order endpoints that allow handling draft orders in Medusa.",
+      "x-resourceId": "draft-order"
+    },
     {
       "name": "Gift Card",
+      "description": "Gift Card endpoints that allow handling gift cards in Medusa.",
       "x-resourceId": "gift_card"
     },
+    {
+      "name": "Invite",
+      "description": "Invite endpoints that allow handling invites in Medusa.",
+      "x-resourceId": "invite"
+    },
+    {
+      "name": "Note",
+      "description": "Note endpoints that allow handling notes in Medusa.",
+      "x-resourceId": "note"
+    },
     {
       "name": "Notification",
+      "description": "Notification endpoints that allow handling notifications in Medusa.",
       "x-resourceId": "notification"
     },
     {
       "name": "Order",
+      "description": "Order endpoints that allow handling orders in Medusa.",
       "x-resourceId": "order"
     },
+    {
+      "name": "Price List",
+      "description": "Price List endpoints that allow handling price lists in Medusa.",
+      "x-resourceId": "price_list"
+    },
     {
       "name": "Product",
+      "description": "Product endpoints that allow handling products in Medusa.",
       "x-resourceId": "product"
     },
+    {
+      "name": "Product Tag",
+      "description": "Product Tag endpoints that allow handling product tags in Medusa.",
+      "x-resourceId": "product_tag"
+    },
+    {
+      "name": "Product Types",
+      "description": "Product Types endpoints that allow handling product types in Medusa.",
+      "x-resourceId": "product_type"
+    },
+    {
+      "name": "Product Variant",
+      "description": "Product Variant endpoints that allow handling product variants in Medusa.",
+      "x-resourceId": "product_variant"
+    },
     {
       "name": "Region",
+      "description": "Region endpoints that allow handling regions in Medusa.",
       "x-resourceId": "region"
     },
+    {
+      "name": "Return Reason",
+      "description": "Return Reason endpoints that allow handling return reasons in Medusa.",
+      "x-resourceId": "return_reason"
+    },
     {
       "name": "Return",
+      "description": "Return endpoints that allow handling returns in Medusa.",
       "x-resourceId": "return"
     },
+    {
+      "name": "Sales Channel",
+      "description": "Sales Channel endpoints that allow handling sales channels in Medusa.",
+      "x-resourceId": "sales_channel"
+    },
     {
       "name": "Shipping Option",
+      "description": "Shipping Option endpoints that allow handling shipping options in Medusa.",
       "x-resourceId": "shipping_option"
     },
     {
       "name": "Shipping Profile",
+      "description": "Shipping Profile endpoints that allow handling shipping profiles in Medusa.",
       "x-resourceId": "shipping_profile"
     },
+    {
+      "name": "Store",
+      "description": "Store endpoints that allow handling stores in Medusa.",
+      "x-resourceId": "store"
+    },
     {
       "name": "Swap",
+      "description": "Swap endpoints that allow handling swaps in Medusa.",
       "x-resourceId": "swap"
     },
     {
-      "name": "Product Variant",
-      "x-resourceId": "product_variant"
+      "name": "Tax Rate",
+      "description": "Tax Rate endpoints that allow handling tax rates in Medusa.",
+      "x-resourceId": "tax_rate"
     },
     {
-      "name": "OAuth",
-      "x-resourceId": "OAuth"
+      "name": "Upload",
+      "description": "Upload endpoints that allow handling uploads in Medusa."
+    },
+    {
+      "name": "User",
+      "description": "User endpoints that allow handling users in Medusa.",
+      "x-resourceId": "user"
     }
   ],
   "servers": [