Swagger

README.md

@@ -4,7 +4,8 @@
 Rest API of images of fumos (japanese plushies) using typescript and fastify.
 
 ![logo](https://repository-images.githubusercontent.com/395606928/753b9fdd-b978-4b74-841e-f3973daf9129)
-
+## Documentation
+Documentation available at [fumo-api.nosesisaid.com/docs](https://fumo-api.nosesisaid.com/docs)
 ## Contributing
 if you would like something to be different or have any suggestion, please [open an issue](https://github.com/nosesisaid/fumo-api/issues/new).
 

package.json

@@ -7,6 +7,7 @@
   "scripts": {
     "start": "node dist/server.js",
     "lint": "eslint src",
+    "lint:fix": "eslint src --fix",
     "build": "tsc",
     "dev": "yarn build && yarn start",
     "test": "tap --no-coverage"
@@ -16,6 +17,7 @@
   "dependencies": {
     "@fastify/cors": "7.0.0",
     "@fastify/mongodb": "5.0.0",
+    "@fastify/swagger": "6.x",
     "dotenv": "16.0.1",
     "fastify": "3.29.0"
   },

src/App.ts

@@ -2,40 +2,172 @@ import fastify, { FastifyServerOptions } from 'fastify';
 import fastifyMongodb from '@fastify/mongodb';
 import './config/env';
 import cors from '@fastify/cors';
+import fastifySwagger from '@fastify/swagger';
 
-function build(opts:FastifyServerOptions={}) {
+async function build(opts: FastifyServerOptions = {}, isTest = false) {
 	const App = fastify(opts);
 
 	App.register(fastifyMongodb, {
-		url: process.env.MONGO_URL
+		url: process.env.MONGO_URL,
 	});
 	App.register(cors, {
-		origin: '*'
+		origin: '*',
 	});
-
-	App.get('/', async (req, res) => {
-		const fumos = await App.mongo.db?.collection('fumos').find({}).toArray();
-
+	if (!isTest) {
+		await App.register(fastifySwagger, {
+			routePrefix: '/docs',
+			swagger: {
+				info: {
+					title: 'Fumo-API',
+					description: 'Rest API of images of fumos (japanese plushies).',
+					version: '2.2.0',
+					contact: {
+						email: 'vic@nosesisaid.me',
+						name: 'Nosesisaid',
+						url: 'https://github.com/nosesisaid',
+					},
+					license: {
+						name: 'MIT',
+						url: 'https://opensource.org/licenses/MIT',
+					},
+				},
+				externalDocs: {
+					url: 'https://github.com/nosesisaid/fumo-api',
+					description: 'Find more info here',
+				},
+				host: 'fumo-api.nosesisaid.me',
+				schemes: ['https'],
+				consumes: ['application/json'],
+				produces: ['application/json'],
+				tags: [
+					{ name: 'images', description: 'image related end-points' },
+				],
+				definitions: {
+					Fumo: {
+						type: 'object',
+						required: ['id', 'URL'],
+						properties: {
+							_id: { type: 'string'},
+							URL: { type: 'string' },
+							caption: { type: 'string' },
+							fumos: { type: 'array', } },
+					},
+				},
+
+			},
+			uiConfig: {
+				deepLinking: false,
+			},
+			uiHooks: {
+				onRequest: function (request, reply, next) {
+					next();
+				},
+				preHandler: function (request, reply, next) {
+					next();
+				},
+			},
+			staticCSP: true,
+			transformStaticCSP: (header) => header,
+			exposeRoute: true,
+		});
+	}
+	App.get('/', {
+		schema: {
+			description: 'Get the full list of fumos',
+			tags: ['images'],
+			response: {
+				200: {
+					type: 'array',
+					items: {
+						type: 'object',
+						properties: {
+							_id: { type: 'string' },
+							URL: { type: 'string' },
+							caption: { type: 'string' },
+							fumos: { type: 'array', },
+						},
+					},
+				},
+			},
+		},
+	},async (req, res) => {
+		const fumos = await App.mongo.db?.collection('fumos').find({}).toArray();	
 		res.status(200).send(fumos);
 	});
 
-	App.get('/fumo/:id', async (req, res) => {
-
-		const id = (req as any).params.id;
-		const fumo = await (await App.mongo.db?.collection('fumos'))?.findOne({_id: id});
+	App.get('/fumo/:id',{
+		schema: {
+			description: 'Get a fumo by it\'s id',
+			tags: ['images'],
+			params: {
+				type: 'object',
+				properties: {
+					_id: { type: 'string', description: 'The id of the fumo' },
+				},
+			},
+			response: {
+				200: {
+					type: 'object',
+					properties: {
+						_id: { type: 'string' },
+						URL: { type: 'string' },
+						caption: { type: 'string' },
+						fumos: { type: 'array', },
+					},
+				},
+			},
+		},
+	}, async (req, res) => {
+		const params = req.params;
+		const fumo = await (await App.mongo.db?.collection('fumos'))?.findOne({_id: (params as any).id});
 
 		res.status(200).send(fumo);
 	});
 
-	App.get('/random', async (req,res)=> {
+	App.get('/random', {
+		schema: {
+			description: 'Get a random fumo',
+			tags: ['images'],
+			response: {
+				200: {
+					type: 'object',
+					properties: {
+						_id: { type: 'string' },
+						URL: { type: 'string' },
+						caption: { type: 'string' },
+						fumos: { type: 'array', },
+					},
+				},
+			},
+		},
+	}, async (req, res) => {
 		const fumos = await App.mongo.db?.collection('fumos').find({}).toArray();
 		if (!fumos) return res.status(400).send('No fumo :( (server error)');
 		const fumo = fumos[Math.floor(Math.random() * fumos?.length)];
-    
+
 		res.status(200).send(fumo);
 	});
 
-	App.get('/fumos', async(req, res) => {
+	App.get('/fumos', {
+		schema: {
+			description: 'Get a list of fumos',
+			tags: ['images'],
+			response: {
+				200: {
+					type: 'array',
+					items: {
+						type: 'object',
+						properties: {
+							_id: { type: 'string' },
+							URL: { type: 'string' },
+							caption: { type: 'string' },
+							fumos: { type: 'array', },
+						},
+					},
+				},
+			},
+		},
+	}, async (req, res) => {
 		const fumos = await App.mongo.db?.collection('fumos').find({}).toArray();
 
 		res.status(200).send(fumos);

src/server.ts

@@ -1,11 +1,15 @@
 import {PORT} from './config/env';
 import build from './App';
-
-const server = build({
-	logger: true
-});
-
-server.listen(PORT,'0.0.0.0', err => {
-	if (err) throw err;
-	console.log('Server listening on port ' + PORT);
-});
+async function main() {
+
+	const server = await build({
+		logger: true
+	});
+	await server.ready();
+	await server.swagger();
+	server.listen(PORT,'0.0.0.0', err => {
+		if (err) throw err;
+		console.log('Server listening on port ' + PORT);
+	});
+}
+main();

tests/random.test.js

@@ -2,7 +2,7 @@ const build = require("../dist/App.js").default;
 const {test} = require("tap");
 test('call `/random` route', async (t) => {
     t.plan(2)
-    const app = build();
+    const app = await build();
     const response = await app.inject({
         method: 'GET',
         url:'/random'

tests/root.test.js

@@ -4,7 +4,7 @@ const { test } = require("tap");
 test('call `/` route', async (t) => {
     t.plan(2);
 
-    const app = build();
+    const app = await build();
     const response = await app.inject({
         method: 'GET',
         url:'/'

tests/specific.test.js

@@ -3,7 +3,7 @@ const {test} = require("tap");
 
 test('call `/fumo/id` route', async (t) => {
     t.plan(4)
-    const app = build();
+    const app = await build();
     const id = '6128c5578caf0cf9a83f73e8';
     const response = await app.inject({
         method: 'GET',