From 01b9b791f36811b68fbb75c2a5f33cc78ce92773 Mon Sep 17 00:00:00 2001
From: Charles <charles-francis.damedey@savoirfairelinux.com>
Date: Fri, 21 Jul 2023 14:02:59 -0400
Subject: [PATCH] misc: add api documentation
GitLab: #4
Change-Id: I5820981f64599b9abffef478da8496e27fe0f32a
---
src/controllers/plugins.controller.ts | 210 +++++++++++++++++++++++---
1 file changed, 192 insertions(+), 18 deletions(-)
diff --git a/src/controllers/plugins.controller.ts b/src/controllers/plugins.controller.ts
index cd0955b..273b6c2 100644
--- a/src/controllers/plugins.controller.ts
+++ b/src/controllers/plugins.controller.ts
@@ -30,27 +30,52 @@ export class PluginsController {
this.configureRouter();
}
- /**
- * @swagger
- *
- * /plugins:arch:
- * get:
- * description: Returns the plugins for a given architecture
- * tags:
- * - Example
- * - Time
- * produces:
- * - application/json
- * responses:
- * 200:
- * schema:
- * $ref: '#/definitions/Message'
- */
private configureRouter(): void {
- // GET /plugins
if (this.router === undefined) {
this.router = Router();
}
+ /**
+ * @swagger
+ * tags:
+ * name: Example
+ * description: Example API endpoints
+ * externalDocs:
+ * description: Find out more about Example
+ * url: http://example.com
+ *
+ * /plugins:
+ * get:
+ * summary: Get plugins for a given architecture
+ * description: Returns the plugins for a given architecture.
+ * tags: [Example, Time]
+ * parameters:
+ * - name: arch
+ * in: query
+ * description: The architecture for which plugins are requested.
+ * required: true
+ * schema:
+ * type: string
+ * responses:
+ * '200':
+ * description: Successful response with the plugins data.
+ * content:
+ * application/json:
+ * schema:
+ * type: array
+ * items:
+ * type: object
+ * properties:
+ * name:
+ * type: string
+ * version:
+ * type: string
+ * author:
+ * type: string
+ * '400':
+ * description: Bad request - When the 'arch' parameter is missing.
+ * '500':
+ * description: Internal server error - Something went wrong on the server.
+ */
// eslint-disable-next-line @typescript-eslint/no-misused-promises
this.router.get('/', async (req: Request, res: Response) => {
try {
@@ -66,6 +91,48 @@ export class PluginsController {
}
});
+ /**
+ * @swagger
+ *
+ * /details/:id:
+ * get:
+ * summary: Get details of a plugin for a given ID and architecture
+ * description: Returns details of a plugin for a given ID and architecture.
+ * tags: [Example, Time]
+ * parameters:
+ * - name: id
+ * in: path
+ * description: The ID of the plugin.
+ * required: true
+ * schema:
+ * type: string
+ * - name: arch
+ * in: query
+ * description: The architecture for which the plugin details are requested.
+ * required: true
+ * schema:
+ * type: string
+ * responses:
+ * '200':
+ * description: Successful response with the plugin details.
+ * content:
+ * application/json:
+ * schema:
+ * type: object
+ * properties:
+ * name:
+ * type: string
+ * version:
+ * type: string
+ * author:
+ * type: string
+ * '400':
+ * description: Bad request - When the 'id' or 'arch' parameter is missing.
+ * '404':
+ * description: Not found - When the plugin with the specified ID is not found.
+ * '500':
+ * description: Internal server error - Something went wrong on the server.
+ */
// GET /details/:id?arch=:arch
// eslint-disable-next-line @typescript-eslint/no-misused-promises
this.router.get('/details/:id', async (req: Request, res: Response) => {
@@ -88,6 +155,44 @@ export class PluginsController {
}
});
+ /**
+ * @swagger
+ *
+ * /download/{arch}/{id}:
+ * get:
+ * summary: Download a plugin file for a given ID and architecture
+ * description: Download a plugin file for a given ID and architecture.
+ * tags: [Example, Time]
+ * parameters:
+ * - name: id
+ * in: path
+ * description: The ID of the plugin to be downloaded.
+ * required: true
+ * schema:
+ * type: string
+ * - name: arch
+ * in: path
+ * description: The architecture for which the plugin is requested.
+ * required: true
+ * schema:
+ * type: string
+ * responses:
+ * '200':
+ * description: Successful response with the plugin file download.
+ * content:
+ * application/octet-stream:
+ * schema:
+ * type: string
+ * format: binary
+ * '400':
+ * description: Bad request - When the 'id' or 'arch' parameter is missing.
+ * '404':
+ * description: Not found - When the plugin file with the specified ID and architecture is not found.
+ * '500':
+ * description: Internal server error - Something went wrong on the server.
+ *
+ */
+
// GET /download/:arch/:id
// eslint-disable-next-line @typescript-eslint/no-misused-promises
this.router.get(
@@ -123,7 +228,44 @@ export class PluginsController {
}
);
- // GET /icon/:id?arch=:arch
+ /**
+ * @swagger
+ *
+ * /icons/{id}:
+ * get:
+ * summary: Get the icon for a plugin with a given ID and architecture
+ * description: Returns the icon for a plugin with a given ID and architecture.
+ * tags: [Example, Time]
+ * parameters:
+ * - name: id
+ * in: path
+ * description: The ID of the plugin to get the icon for.
+ * required: true
+ * schema:
+ * type: string
+ * - name: arch
+ * in: query
+ * description: The architecture for which the plugin icon is requested.
+ * required: true
+ * schema:
+ * type: string
+ * responses:
+ * '200':
+ * description: Successful response with the plugin icon image.
+ * content:
+ * image/svg+xml:
+ * schema:
+ * type: string
+ * format: binary
+ * '400':
+ * description: Bad request - When the 'id' or 'arch' parameter is missing.
+ * '404':
+ * description: Not found - When the plugin icon with the specified ID and architecture is not found.
+ * '500':
+ * description: Internal server error - Something went wrong on the server.
+ */
+
+ // GET /icons/:id?arch=:arch
// eslint-disable-next-line
this.router.get('/icons/:id', async (req: Request, res: Response) => {
try {
@@ -146,6 +288,38 @@ export class PluginsController {
}
});
+ /**
+ * @swagger
+ *
+ * /versions:
+ * get:
+ * summary: Get the versions of a plugin for a given architecture
+ * description: Returns the versions of a plugin for a given architecture.
+ * tags: [Example, Time]
+ * parameters:
+ * - name: arch
+ * in: query
+ * description: The architecture for which plugin versions are requested.
+ * required: true
+ * schema:
+ * type: string
+ * responses:
+ * '200':
+ * description: Successful response with the plugin versions.
+ * content:
+ * application/json:
+ * schema:
+ * type: array
+ * items:
+ * type: string
+ * '400':
+ * description: Bad request - When the 'arch' parameter is missing.
+ * '404':
+ * description: Not found - When no plugin versions are available for the specified architecture.
+ * '500':
+ * description: Internal server error - Something went wrong on the server.
+ */
+
// GET /versions/:id?arch=:arch
// eslint-disable-next-line @typescript-eslint/no-misused-promises
this.router.get('/versions/', async (req: Request, res: Response) => {
--
GitLab