[Closes #46] Integrate @fastify/swagger and Scalar

server/package.json

@@ -28,8 +28,10 @@
     "@fastify/cookie": "^9.3.1",
     "@fastify/secure-session": "^7.1.0",
     "@fastify/sensible": "^5.5.0",
+    "@fastify/swagger": "^8.14.0",
     "@getbigger-io/prisma-fixtures-cli": "^2.0.1",
     "@prisma/client": "^5.12.0",
+    "@scalar/fastify-api-reference": "^1.20.20",
     "bcrypt": "^5.1.1",
     "dotenv": "^16.4.5",
     "fastify": "^4.26.1",

server/plugins/swagger.js

@@ -0,0 +1,37 @@
+import fp from 'fastify-plugin';
+import swagger from '@fastify/swagger';
+import scalar from '@scalar/fastify-api-reference';
+
+import fs from 'fs/promises';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+const pkg = await fs.readFile(path.resolve(__dirname, '../../package.json'), {
+  encoding: 'utf8',
+});
+const { version } = JSON.parse(pkg);
+
+/**
+ * This adds Swagger support to our API endpoints for generating documentation.
+ */
+export default fp(async (fastify) => {
+  await fastify.register(swagger, {
+    openapi: {
+      info: {
+        title: 'SF Life Line API',
+        version,
+      },
+      servers: [
+        {
+          url: 'http://localhost:5000',
+        },
+      ],
+    },
+  });
+  await fastify.register(scalar, {
+    routePrefix: '/api/reference',
+  });
+});

server/routes/api/v1/auth/index.js

@@ -17,14 +17,15 @@ export default async function (fastify, _opts) {
         },
         response: {
           200: {
-            type: 'object',
-            properties: {
-              id: { type: 'string' },
-              firstName: { type: 'string' },
-              lastName: { type: 'string' },
-              email: { type: 'string', format: 'email' },
-              role: { type: 'string' },
-              createdAt: { type: 'string' },
+            type: 'null',
+            description:
+              'Successfully authenticated. The response sets a cookie named `session` that should be sent in subsequent requests for authentication. This cookie will NOT appear in the web-based API tester infterface because it is an HttpOnly cookie that cannot be accessed by JavaScript.',
+            headers: {
+              'Set-Cookie': {
+                schema: {
+                  type: 'string',
+                },
+              },
             },
           },
         },

server/routes/api/v1/licenses/index.js

@@ -2,7 +2,7 @@ import verifyLicense from '../../../../helpers/license/verifyLicense.js';
 
 export default async function (fastify) {
   fastify.get(
-    '/',
+    '',
     {
       schema: {
         querystring: {

server/routes/api/v1/users/index.js

@@ -13,13 +13,13 @@ export default async function (fastify, _opts) {
       schema: {
         body: {
           type: 'object',
-          required: ['firstName', 'lastName', 'email'],
+          required: ['firstName', 'lastName', 'email', 'password'],
           properties: {
             firstName: { type: 'string' },
             middleName: { type: 'string' },
             lastName: { type: 'string' },
             email: { type: 'string', format: 'email' },
-            hashedPassword: { type: 'string' },
+            password: { type: 'string' },
             licenseNumber: { type: 'string' },
           },
         },
@@ -90,7 +90,7 @@ export default async function (fastify, _opts) {
 
   // Read All Users
   fastify.get(
-    '/',
+    '',
     {
       schema: {
         response: {

server/test/routes/root.test.js → server/test/routes/api/index.test.js

@@ -2,15 +2,15 @@ import { describe, it } from 'node:test';
 import * as assert from 'node:assert';
 import { StatusCodes } from 'http-status-codes';
 
-import { build } from '../helper.js';
+import { build } from '../../helper.js';
 
-describe('/', () => {
+describe('/api', () => {
   describe('GET /health', () => {
     it('returns ok when the server is up and running', async (t) => {
       const app = await build(t);
 
       const res = await app.inject({
-        url: '/health',
+        url: '/api/health',
       });
       assert.deepStrictEqual(res.statusCode, StatusCodes.OK);
       assert.deepStrictEqual(JSON.parse(res.payload), { status: 'OK' });