feat: add basis api documentation

apps/server/src/app/app.ts

@@ -6,6 +6,9 @@ import * as Sentry from '@sentry/node'
 import * as SentryTracing from '@sentry/tracing'
 import * as trpcExpress from '@trpc/server/adapters/express'
 import { appRouter, createTRPCContext } from './trpc'
+import { apiReference } from '@scalar/express-api-reference'
+import swaggerJsdoc from 'swagger-jsdoc'
+
 /**
  * In Express 4.x, asynchronous errors are NOT automatically passed to next().  This middleware is a small
  * wrapper around Express that enables automatic async error handling
@@ -45,6 +48,7 @@ import {
     e2eRouter,
 } from './routes'
 import env from '../env'
+import maybeScalarTheme from './maybe-scalar-theme'
 
 const app = express()
 
@@ -165,6 +169,32 @@ app.use('/v1/holdings', holdingsRouter)
 app.use('/v1/securities', securitiesRouter)
 app.use('/v1/plans', plansRouter)
 
+// api docs
+const options = {
+    definition: {
+        openapi: '3.0.0',
+        info: {
+            title: 'Maybe API References',
+            description:
+                'This page may not represent the current state of the API and is primarily here as a quick reference to see everything in one spot.',
+            version: '1.0.0',
+        },
+    },
+    apis: ['**/routes/**.router.ts'],
+}
+
+const openapiSpecification = swaggerJsdoc(options)
+
+app.use(
+    '/reference',
+    apiReference({
+        customCss: maybeScalarTheme,
+        spec: {
+            content: openapiSpecification,
+        },
+    })
+)
+
 // Sentry must be the *first* handler
 app.use(identifySentryUser)
 app.use(Sentry.Handlers.errorHandler())

apps/server/src/app/routes/account-rollup.router.ts

@@ -5,6 +5,26 @@ import endpoint from '../lib/endpoint'
 
 const router = Router()
 
+/**
+ * @swagger
+ * tags:
+ *   name: Account Rollups
+ *   description: Account rollups
+ */
+
+/**
+ * @swagger
+ * /:
+ *   get:
+ *     description: Returns accounts
+ *     tags:
+ *      - Account Rollups
+ *     produces:
+ *      - application/json
+ *     responses:
+ *       200:
+ *         description: users
+ */
 router.get(
     '/',
     endpoint.create({

apps/server/src/app/routes/accounts.router.ts

@@ -13,6 +13,13 @@ import endpoint from '../lib/endpoint'
 import keyBy from 'lodash/keyBy'
 import merge from 'lodash/merge'
 
+/**
+ * @swagger
+ * tags:
+ *   name: Accounts
+ *   description: Accounts
+ */
+
 const router = Router()
 
 router.get(

apps/server/src/app/routes/connections.router.ts

@@ -8,6 +8,26 @@ import { devOnly } from '../middleware'
 
 const router = Router()
 
+/**
+ * @swagger
+ * tags:
+ *   name: Account Connections
+ *   description: Account Connections
+ */
+
+/**
+ * @swagger
+ * /:id:
+ *   get:
+ *     description: Returns connections
+ *     tags:
+ *      - Account Connections
+ *     produces:
+ *      - application/json
+ *     responses:
+ *       200:
+ *         description: users
+ */
 router.get(
     '/:id',
     endpoint.create({

apps/server/src/app/routes/institutions.router.ts

@@ -4,6 +4,26 @@ import endpoint from '../lib/endpoint'
 
 const router = Router()
 
+/**
+ * @swagger
+ * tags:
+ *   name: Institutions
+ *   description: Institutions
+ */
+
+/**
+ * @swagger
+ * /:
+ *   get:
+ *     description: Returns instriutions
+ *     tags:
+ *      - Institutions
+ *     produces:
+ *      - application/json
+ *     responses:
+ *       200:
+ *         description: users
+ */
 router.get(
     '/',
     endpoint.create({

apps/server/src/app/routes/plaid.router.ts

@@ -6,6 +6,26 @@ import { devOnly } from '../middleware'
 
 const router = Router()
 
+/**
+ * @swagger
+ * tags:
+ *   name: Plaid
+ *   description: Plaid
+ */
+
+/**
+ * @swagger
+ * /status:
+ *   get:
+ *     description: Returns status
+ *     tags:
+ *      - Plaid
+ *     produces:
+ *      - application/json
+ *     responses:
+ *       200:
+ *         description: users
+ */
 router.get(
     '/status',
     endpoint.create({

apps/server/src/app/routes/users.router.ts

@@ -10,6 +10,13 @@ import {
     UpdateOnboardingSchema,
 } from '@maybe-finance/server/features'
 
+/**
+ * @swagger
+ * tags:
+ *   name: Users
+ *   description: User management and login
+ */
+
 const router = Router()
 
 router.get(
@@ -21,6 +28,19 @@ router.get(
     })
 )
 
+/**
+ * @swagger
+ * /onboarding/:flow:
+ *   get:
+ *     description: Returns users
+ *     tags:
+ *      - Users
+ *     produces:
+ *      - application/json
+ *     responses:
+ *       200:
+ *         description: users
+ */
 router.get(
     '/onboarding/:flow',
     endpoint.create({

apps/server/src/app/routes/valuations.router.ts

@@ -6,6 +6,26 @@ import { DateUtil } from '@maybe-finance/shared'
 
 const router = Router()
 
+/**
+ * @swagger
+ * tags:
+ *   name: Valuations
+ *   description: Valuations
+ */
+
+/**
+ * @swagger
+ * /:id:
+ *   get:
+ *     description: Returns valuations
+ *     tags:
+ *      - Valuations
+ *     produces:
+ *      - application/json
+ *     responses:
+ *       200:
+ *         description: users
+ */
 router.get(
     '/:id',
     endpoint.create({

apps/server/src/app/routes/webhooks.router.ts

@@ -8,6 +8,26 @@ import env from '../../env'
 
 const router = Router()
 
+/**
+ * @swagger
+ * tags:
+ *   name: Webhooks
+ *   description: Webhooks
+ */
+
+/**
+ * @swagger
+ * /plaid/webhook:
+ *   get:
+ *     description: Webhook for plaid
+ *     tags:
+ *      - Webhooks
+ *     produces:
+ *      - application/json
+ *     responses:
+ *       200:
+ *         description: users
+ */
 router.post(
     '/plaid/webhook',
     process.env.NODE_ENV !== 'development' ? validatePlaidJwt : (_req, _res, next) => next(),

package.json

@@ -45,6 +45,7 @@
         "@polygon.io/client-js": "^6.0.6",
         "@popperjs/core": "^2.11.5",
         "@prisma/client": "^5.8.0",
+        "@scalar/express-api-reference": "^0.2.12",
         "@sentry/node": "^7.22.0",
         "@sentry/react": "^7.22.0",
         "@sentry/tracing": "^7.22.0",
@@ -154,6 +155,7 @@
         "smooth-scroll-into-view-if-needed": "^1.1.33",
         "stripe": "^10.17.0",
         "superjson": "^1.11.0",
+        "swagger-jsdoc": "^6.2.8",
         "tailwindcss": "3.2.4",
         "tslib": "^2.3.0",
         "uuid": "^9.0.0",