feat: add docusaurus-preset-openapi

package.json

@@ -11,6 +11,7 @@
     "build:server": "tsc -p tsconfig.server.json",
     "build:tracker": "ts-node scripts/build-tracker.ts",
     "build:geo": "ts-node scripts/build-geo.ts",
+    "build:openapi": "ts-node scripts/build-openapi-schema.ts",
     "postinstall": "pnpm db:generate",
     "check:type": "tsc --noEmit --skipLibCheck --module esnext",
     "db:push": "prisma db push",
@@ -86,6 +87,7 @@
     "@types/compression": "^1.7.2",
     "@types/cors": "^2.8.15",
     "@types/express": "^4.17.17",
+    "@types/fs-extra": "^11.0.3",
     "@types/jsonwebtoken": "^9.0.2",
     "@types/lodash": "^4.14.198",
     "@types/lodash-es": "^4.17.9",
@@ -103,6 +105,7 @@
     "@vitejs/plugin-react": "^4.0.4",
     "autoprefixer": "^10.4.15",
     "cross-env": "^7.0.3",
+    "fs-extra": "^11.1.1",
     "nodemon": "^2.0.22",
     "postcss": "^8.4.29",
     "prisma": "^5.4.2",

pnpm-lock.yaml

@@ -195,6 +195,9 @@ devDependencies:
   '@types/express':
     specifier: ^4.17.17
     version: 4.17.17
+  '@types/fs-extra':
+    specifier: ^11.0.3
+    version: 11.0.3
   '@types/jsonwebtoken':
     specifier: ^9.0.2
     version: 9.0.2
@@ -246,6 +249,9 @@ devDependencies:
   cross-env:
     specifier: ^7.0.3
     version: 7.0.3
+  fs-extra:
+    specifier: ^11.1.1
+    version: 11.1.1
   nodemon:
     specifier: ^2.0.22
     version: 2.0.22
@@ -2081,6 +2087,13 @@ packages:
       '@types/serve-static': 1.15.2
     dev: true
 
+  /@types/fs-extra@11.0.3:
+    resolution: {integrity: sha512-sF59BlXtUdzEAL1u0MSvuzWd7PdZvZEtnaVkzX5mjpdWTJ8brG0jUqve3jPCzSzvAKKMHTG8F8o/WMQLtleZdQ==}
+    dependencies:
+      '@types/jsonfile': 6.1.3
+      '@types/node': 18.17.12
+    dev: true
+
   /@types/geojson@7946.0.10:
     resolution: {integrity: sha512-Nmh0K3iWQJzniTuPRcJn5hxXkfB1T1pgB89SBig5PlJQU5yocazeu4jATJlaA0GYFKWMqDdvYemoSnF2pXgLVA==}
     dev: false
@@ -2093,6 +2106,12 @@ packages:
     resolution: {integrity: sha512-aLkWa0C0vO5b4Sr798E26QgOkss68Un0bLjs7u9qxzPT5CG+8DuNTffWES58YzJs3hrVAOs1wonycqEBqNJubA==}
     dev: false
 
+  /@types/jsonfile@6.1.3:
+    resolution: {integrity: sha512-/yqTk2SZ1wIezK0hiRZD7RuSf4B3whFxFamB1kGStv+8zlWScTMcHanzfc0XKWs5vA1TkHeckBlOyM8jxU8nHA==}
+    dependencies:
+      '@types/node': 18.17.12
+    dev: true
+
   /@types/jsonwebtoken@9.0.2:
     resolution: {integrity: sha512-drE6uz7QBKq1fYqqoFKTDRdFCPHd5TCub75BM+D+cMx7NU9hUz7SESLfC2fSCXVFMO5Yj8sOWHuGqPgjc+fz0Q==}
     dependencies:
@@ -3755,6 +3774,15 @@ packages:
     engines: {node: '>= 0.6'}
     dev: false
 
+  /fs-extra@11.1.1:
+    resolution: {integrity: sha512-MGIE4HOvQCeUCzmlHs0vXpih4ysz4wg9qiSAu6cd42lVwPbTM1TjV7RusoyQqMmk/95gdQZX72u+YW+c3eEpFQ==}
+    engines: {node: '>=14.14'}
+    dependencies:
+      graceful-fs: 4.2.11
+      jsonfile: 6.1.0
+      universalify: 2.0.0
+    dev: true
+
   /fs-extra@8.1.0:
     resolution: {integrity: sha512-yhlQgA6mnOJUKOsRUFsgJdQCvkKhcz8tlZG5HBQfReYZy46OwLcY+Zia0mtdHsOo9y/hP+CxMN0TU9QxoOtG4g==}
     engines: {node: '>=6 <7 || >=8'}
@@ -3918,7 +3946,6 @@ packages:
 
   /graceful-fs@4.2.11:
     resolution: {integrity: sha512-RbJ5/jmFcNNCcDV5o9eTnBLJ/HszWV0P73bc+Ff4nS/rJj+YaS6IGyiOL0VoBYX+l1Wrl3k63h/KrH+nhJ0XvQ==}
-    dev: false
 
   /graphlib@2.1.8:
     resolution: {integrity: sha512-jcLLfkpoVGmH7/InMC/1hIvOPSUh38oJtGhvrOFGzioE1DZ+0YW16RgmOJhHiuWTvGiJQ9Z1Ik43JvkRPRvE+A==}
@@ -4342,6 +4369,14 @@ packages:
       graceful-fs: 4.2.11
     dev: false
 
+  /jsonfile@6.1.0:
+    resolution: {integrity: sha512-5dgndWOriYSm5cnYaJNhalLNDKOqFwyDB/rr1E9ZsGciGvKPs8R2xYGCacuf3z6K1YKDz182fd+fY3cn3pMqXQ==}
+    dependencies:
+      universalify: 2.0.0
+    optionalDependencies:
+      graceful-fs: 4.2.11
+    dev: true
+
   /jsonwebtoken@9.0.2:
     resolution: {integrity: sha512-PRp66vJ865SSqOlgqS8hujT5U4AOgMfhrwYIuIhfKaoSCZcirrmASQr8CX7cUg+RMih+hgznrjp99o+W4pJLHQ==}
     engines: {node: '>=12', npm: '>=6'}
@@ -7011,6 +7046,11 @@ packages:
     engines: {node: '>= 4.0.0'}
     dev: false
 
+  /universalify@2.0.0:
+    resolution: {integrity: sha512-hAZsKq7Yy11Zu1DE0OzWjw7nnLZmJZYTDZZyEFHZdUhV8FkH5MCfoU1XMaxXovpyW5nq5scPqq0ZDP9Zyl04oQ==}
+    engines: {node: '>= 10.0.0'}
+    dev: true
+
   /unpipe@1.0.0:
     resolution: {integrity: sha512-pjy2bYhSsufwWlKwPc+l3cN7+wuJlK6uz0YdJEOlQDbl6jo/YlPi4mb8agUkVC8BF7V8NuzeyPNqRksA3hztKQ==}
     engines: {node: '>= 0.8'}

scripts/build-openapi-schema.ts

@@ -0,0 +1,12 @@
+import { trpcOpenapiDocument } from '../src/server/trpc';
+import fs from 'fs-extra';
+import path from 'path';
+
+const target = path.resolve(__dirname, '../website/openapi.json');
+fs.writeJSON(target, trpcOpenapiDocument)
+  .then(() => {
+    console.log('openapi schema has been write into:', target);
+  })
+  .catch((err) => {
+    console.error(err);
+  });

src/server/trpc/index.ts

@@ -5,6 +5,7 @@ import {
   createOpenApiHttpHandler,
   generateOpenApiDocument,
 } from 'trpc-openapi';
+import { version } from '../../../package.json';
 
 export const trpcExpressMiddleware = trpcExpress.createExpressMiddleware({
   router: appRouter,
@@ -26,6 +27,6 @@ const description = `
 export const trpcOpenapiDocument = generateOpenApiDocument(appRouter, {
   title: 'Tianji OpenAPI',
   description,
-  version: '1.0.0',
+  version: `v${version}`,
   baseUrl: '/open',
 });

website/docusaurus.config.js

@@ -34,28 +34,24 @@ const config = {
 
   presets: [
     [
-      'classic',
+      'docusaurus-preset-openapi',
-      /** @type {import('@docusaurus/preset-classic').Options} */
+      /** @type {import('docusaurus-preset-openapi').Options} */
-      ({
+      {
-        docs: {
+        api: {
-          sidebarPath: require.resolve('./sidebars.js'),
+          path: "./openapi.json",
-          // Please change this to your repo.
+          routeBasePath: "/api",
-          // Remove this to remove the "edit this page" links.
-          editUrl:
-            'https://github.com/facebook/docusaurus/tree/main/packages/create-docusaurus/templates/shared/',
         },
-        blog: {
+        docs: {
-          showReadingTime: true,
+          sidebarPath: require.resolve("./sidebars.js"),
-          // Please change this to your repo.
+          routeBasePath: "/",
-          // Remove this to remove the "edit this page" links.
           editUrl:
             'https://github.com/facebook/docusaurus/tree/main/packages/create-docusaurus/templates/shared/',
         },
         theme: {
-          customCss: require.resolve('./src/css/custom.css'),
+          customCss: require.resolve("./src/css/custom.css"),
         },
-      }),
+      },
-    ],
+    ]
   ],
 
   themeConfig:
@@ -76,7 +72,7 @@ const config = {
             position: 'left',
             label: 'Tutorial',
           },
-          { to: '/blog', label: 'Blog', position: 'left' },
+          { to: '/api', label: 'API', position: 'left' },
           {
             href: 'https://github.com/facebook/docusaurus',
             label: 'GitHub',

website/package.json

@@ -19,6 +19,7 @@
     "@docusaurus/preset-classic": "2.4.3",
     "@mdx-js/react": "^1.6.22",
     "clsx": "^1.2.1",
+    "docusaurus-preset-openapi": "^0.6.4",
     "prism-react-renderer": "^1.3.5",
     "react": "^17.0.2",
     "react-dom": "^17.0.2"
@@ -27,7 +28,8 @@
     "@docusaurus/module-type-aliases": "2.4.3",
     "@tsconfig/docusaurus": "^1.0.5",
     "ts-node": "^10.9.1",
-    "typescript": "^4.7.4"
+    "typescript": "^4.7.4",
+    "url": "^0.11.3"
   },
   "browserslist": {
     "production": [