feat(docs): add api documentation with swagger and scalar

- Integrates @fastify/swagger and @scalar/fastify-api-reference to generate API documentation in development
- Adds a new /docs endpoint for the documentation
- Uses tsx for development and starting the server, replacing ts-node and nodemon
- Updates tsconfig.json to use NodeNext module resolution
- Adds tags to each route for better organization in the documentation

Author: 2004durgesh

package.json

@@ -3,8 +3,8 @@
     "version": "1.0.0",
     "main": "src/main.ts",
     "scripts": {
-        "start": "ts-node src/main.ts",
-        "dev": "nodemon src/main.ts",
+        "start": "tsx src/main.ts",
+        "dev": "tsx --watch src/main.ts",
         "build": "tsc",
         "lint": "prettier --write \"src/**/*.ts\""
     },
@@ -25,21 +25,24 @@
     "dependencies": {
         "@consumet/extensions": "github:consumet/consumet.ts",
         "@fastify/cors": "^8.5.0",
-        "@types/node": "^18.11.17",
-        "@types/ws": "^8.5.3",
         "axios": "^1.0.0",
-        "chalk": "4.1.2",
+        "chalk": "^5.6.2",
         "cheerio": "1.0.0-rc.12",
         "dotenv": "^16.0.3",
         "fastify": "^4.10.2",
         "ioredis": "^5.2.4",
         "reconnecting-websocket": "^4.4.0",
-        "ts-node": "^10.9.1",
         "ws": "^8.8.1"
     },
     "devDependencies": {
-        "nodemon": "3.0.1",
+         "@fastify/swagger": "^8.14.0",
+        "@scalar/fastify-api-reference": "^1.40.1",
+        "@types/chalk": "^0.4.31",
+        "@types/node": "^18.11.17",
+        "@types/ws": "^8.5.3",
         "prettier": "^3.0.0",
+        "ts-node": "^10.9.1",
+        "tsx": "^4.21.0",
         "typescript": "5.3.3"
     }
 }

src/main.ts

@@ -39,6 +39,59 @@ export const tmdbApi = process.env.TMDB_KEY && process.env.TMDB_KEY;
     methods: 'GET',
   });
 
+  // Only register Swagger and docs in development
+  if (process.env.NODE_ENV !== 'production') {
+    await fastify.register((await import('@fastify/swagger')).default, {
+      openapi: {
+        info: {
+          title: 'Consumet API',
+          description: 'A REST API for fetching data from various entertainment sources.',
+          version: '1.0.0',
+        },
+        servers: [
+          {
+            url: `http://localhost:${PORT}`,
+            description: 'Local server',
+          },
+        ],
+        'x-tagGroups': [
+          {
+            name: 'Anime',
+            tags: [
+              'hianime',
+              'animekai',
+              'animepahe',
+              'animesaturn',
+              'animeunity',
+              'kickassanime',
+            ],
+          },
+          { name: 'Movies', tags: ['flixhq', 'dramacool', 'goku', 'sflix', 'himovies'] },
+          { name: 'Manga', tags: ['mangadex', 'mangahere', 'mangapill', 'mangareader'] },
+          { name: 'Meta', tags: ['anilist', 'anilist-manga', 'mal', 'tmdb'] },
+          // { name: 'Books', tags: ['books'] },
+          // { name: 'Comics', tags: ['getcomics'] },
+          // { name: 'Light Novels', tags: ['light-novels'] },
+          { name: 'News', tags: ['ann'] },
+        ],
+      } as any,
+    });
+
+    await fastify.register((await import('@scalar/fastify-api-reference')).default, {
+      routePrefix: '/docs',
+      configuration: {
+        title: 'Consumet API Documentation',
+        theme: 'bluePlanet',
+        defaultOpenAllTags: false,
+        hideModels: true,
+        tagsSorter: 'alpha',
+        sidebar: {
+          showOperations: true,
+        },
+      } as any,
+    });
+  }
+
   if (process.env.NODE_ENV === 'DEMO') {
     console.log(chalk.yellowBright('DEMO MODE ENABLED'));
 

src/routes/anime/animekai.ts

@@ -9,6 +9,11 @@ import { Redis } from 'ioredis';
 const routes = async (fastify: FastifyInstance, options: RegisterOptions) => {
   const animekai = new ANIME.AnimeKai();
 
+  fastify.addHook('onRoute', (routeOptions) => {
+    routeOptions.schema = routeOptions.schema || {};
+    routeOptions.schema.tags = ['animekai'];
+  });
+
   fastify.get('/', (_, rp) => {
     rp.status(200).send({
       intro: `Welcome to the animekai provider: check out the provider's website @ ${animekai.toString.baseUrl}`,

src/routes/anime/animepahe.ts

@@ -8,6 +8,11 @@ import { Redis } from 'ioredis';
 const routes = async (fastify: FastifyInstance, options: RegisterOptions) => {
   const animepahe = new ANIME.AnimePahe();
 
+  fastify.addHook('onRoute', (routeOptions) => {
+    routeOptions.schema = routeOptions.schema || {};
+    routeOptions.schema.tags = ['animepahe'];
+  });
+
   fastify.get('/', (_, rp) => {
     rp.status(200).send({
       intro: `Welcome to the animepahe provider: check out the provider's website @ ${animepahe.toString.baseUrl}`,

src/routes/anime/animesaturn.ts

@@ -7,6 +7,11 @@ import cache from '../../utils/cache';
 const routes = async (fastify: FastifyInstance, options: RegisterOptions) => {
   const animesaturn = new ANIME.AnimeSaturn();
 
+  fastify.addHook('onRoute', (routeOptions) => {
+    routeOptions.schema = routeOptions.schema || {};
+    routeOptions.schema.tags = ['animesaturn'];
+  });
+
   fastify.get('/', (_, rp) => {
     rp.status(200).send({
       intro:

src/routes/anime/animeunity.ts

@@ -8,6 +8,11 @@ import { Redis } from 'ioredis';
 const routes = async (fastify: FastifyInstance, options: RegisterOptions) => {
   const animeunity = new ANIME.AnimeUnity();
 
+  fastify.addHook('onRoute', (routeOptions) => {
+    routeOptions.schema = routeOptions.schema || {};
+    routeOptions.schema.tags = ['animeunity'];
+  });
+
   fastify.get('/', (_, rp) => {
     rp.status(200).send({
       intro: `Welcome to the animeunity provider: check out the provider's website @ ${animeunity.toString.baseUrl}`,

src/routes/anime/hianime.ts

@@ -9,6 +9,11 @@ import { Redis } from 'ioredis';
 const routes = async (fastify: FastifyInstance, options: RegisterOptions) => {
   const hianime = new ANIME.Hianime();
 
+  fastify.addHook('onRoute', (routeOptions) => {
+    routeOptions.schema = routeOptions.schema || {};
+    routeOptions.schema.tags = ['hianime'];
+  });
+
   fastify.get('/', (_, rp) => {
     rp.status(200).send({
       intro: `Welcome to the hianime provider: check out the provider's website @ ${hianime.toString.baseUrl}`,

src/routes/anime/index.ts

@@ -16,40 +16,44 @@ const routes = async (fastify: FastifyInstance, options: RegisterOptions) => {
   await fastify.register(animesaturn, { prefix: '/animesaturn' });
   await fastify.register(kickassanime, { prefix: '/kickassanime' });
 
-  fastify.get('/', async (request: any, reply: any) => {
+  fastify.get('/', { schema: { hide: true } }, async (request: any, reply: any) => {
     reply.status(200).send('Welcome to Consumet Anime 🗾');
   });
 
-  fastify.get('/:animeProvider', async (request: FastifyRequest, reply: FastifyReply) => {
-    const queries: { animeProvider: string; page: number } = {
-      animeProvider: '',
-      page: 1,
-    };
-
-    queries.animeProvider = decodeURIComponent(
-      (request.params as { animeProvider: string; page: number }).animeProvider,
-    );
-
-    queries.page = (request.query as { animeProvider: string; page: number }).page;
-
-    if (queries.page! < 1) queries.page = 1;
-
-    const provider = PROVIDERS_LIST.ANIME.find(
-      (provider: any) => provider.toString.name === queries.animeProvider,
-    );
-
-    try {
-      if (provider) {
-        reply.redirect(`/anime/${provider.toString.name}`);
-      } else {
-        reply
-          .status(404)
-          .send({ message: 'Provider not found, please check the providers list.' });
+  fastify.get(
+    '/:animeProvider',
+    { schema: { hide: true } },
+    async (request: FastifyRequest, reply: FastifyReply) => {
+      const queries: { animeProvider: string; page: number } = {
+        animeProvider: '',
+        page: 1,
+      };
+
+      queries.animeProvider = decodeURIComponent(
+        (request.params as { animeProvider: string; page: number }).animeProvider,
+      );
+
+      queries.page = (request.query as { animeProvider: string; page: number }).page;
+
+      if (queries.page! < 1) queries.page = 1;
+
+      const provider = PROVIDERS_LIST.ANIME.find(
+        (provider: any) => provider.toString.name === queries.animeProvider,
+      );
+
+      try {
+        if (provider) {
+          reply.redirect(`/anime/${provider.toString.name}`);
+        } else {
+          reply
+            .status(404)
+            .send({ message: 'Provider not found, please check the providers list.' });
+        }
+      } catch (err) {
+        reply.status(500).send('Something went wrong. Please try again later.');
       }
-    } catch (err) {
-      reply.status(500).send('Something went wrong. Please try again later.');
-    }
-  });
+    },
+  );
 };
 
 export default routes;

src/routes/anime/kickassanime.ts

@@ -9,6 +9,11 @@ import { Redis } from 'ioredis';
 const routes = async (fastify: FastifyInstance, options: RegisterOptions) => {
   const kickassanime = new ANIME.KickAssAnime();
 
+  fastify.addHook('onRoute', (routeOptions) => {
+    routeOptions.schema = routeOptions.schema || {};
+    routeOptions.schema.tags = ['kickassanime'];
+  });
+
   fastify.get('/', (_, rp) => {
     rp.status(200).send({
       intro: `Welcome to the kickassanime provider: check out the provider's website @ ${kickassanime.toString.baseUrl}`,

src/routes/books/index.ts

@@ -1,7 +1,7 @@
 import { FastifyInstance, RegisterOptions } from 'fastify';
 
 const routes = async (fastify: FastifyInstance, options: RegisterOptions) => {
-  fastify.get('/', async (request: any, reply: any) => {
+  fastify.get('/', { schema: { hide: true } }, async (request: any, reply: any) => {
     reply.status(200).send('Welcome to Consumet Books 📚');
   });
 };