feat(api): API documentation with Swagger UI

api/app.ts

@@ -12,6 +12,8 @@ import fastifySession from '@fastify/session';
 import fastifyCookie from '@fastify/cookie';
 import MongoStore from 'connect-mongo';
 import type { TypeBoxTypeProvider } from '@fastify/type-provider-typebox';
+import fastifySwagger from '@fastify/swagger';
+import fastifySwaggerUI from '@fastify/swagger-ui';
 
 import jwtAuthz from './plugins/fastify-jwt-authz';
 import sessionAuth from './plugins/session-auth';
@@ -26,7 +28,9 @@ import {
   AUTH0_DOMAIN,
   NODE_ENV,
   MONGOHQ_URL,
-  SESSION_SECRET
+  SESSION_SECRET,
+  FCC_ENABLE_SWAGGER_UI,
+  API_LOCATION
 } from './utils/env';
 
 export type FastifyInstanceWithTypeProvider = FastifyInstance<
@@ -63,6 +67,30 @@ export const build = async (
     })
   });
 
+  // Swagger plugin
+  if (FCC_ENABLE_SWAGGER_UI) {
+    void fastify.register(fastifySwagger, {
+      openapi: {
+        info: {
+          title: 'freeCodeCamp API',
+          version: '1.0.0' // API version
+        },
+        components: {
+          securitySchemes: {
+            session: {
+              type: 'apiKey',
+              name: 'sessionId',
+              in: 'cookie'
+            }
+          }
+        },
+        security: [{ session: [] }]
+      }
+    });
+    void fastify.register(fastifySwaggerUI);
+    fastify.log.info(`Swagger UI available at ${API_LOCATION}/documentation`);
+  }
+
   // Auth0 plugin
   void fastify.register(fastifyAuth0, {
     domain: AUTH0_DOMAIN,

api/package.json

@@ -7,6 +7,8 @@
     "@fastify/cookie": "^8.3.0",
     "@fastify/middie": "8.1",
     "@fastify/session": "^10.1.1",
+    "@fastify/swagger": "^8.3.1",
+    "@fastify/swagger-ui": "^1.5.0",
     "@prisma/client": "4.11.0",
     "@sinclair/typebox": "0.25.24",
     "connect-mongo": "4.6.0",

api/utils/env.ts

@@ -30,6 +30,7 @@ assert.ok(process.env.AUTH0_DOMAIN);
 assert.ok(process.env.AUTH0_AUDIENCE);
 assert.ok(process.env.API_LOCATION);
 assert.ok(process.env.SESSION_SECRET);
+assert.ok(process.env.FCC_ENABLE_SWAGGER_UI);
 
 if (process.env.NODE_ENV !== 'development' && process.env.NODE_ENV !== 'test') {
   assert.ok(process.env.PORT);
@@ -50,3 +51,5 @@ export const AUTH0_AUDIENCE = process.env.AUTH0_AUDIENCE;
 export const PORT = process.env.PORT || '3000';
 export const API_LOCATION = process.env.API_LOCATION;
 export const SESSION_SECRET = process.env.SESSION_SECRET;
+export const FCC_ENABLE_SWAGGER_UI =
+  process.env.FCC_ENABLE_SWAGGER_UI === 'true';

sample.env

@@ -75,3 +75,4 @@ CODESEE=false
 # ---------------------
 NODE_ENV=development
 PORT=3000
+FCC_ENABLE_SWAGGER_UI=true