[TECH] Proposition de modifications pour le setup de developement

.gitignore

@@ -332,9 +332,9 @@ paket-files/
 
 # IDE - VSCode
 .vscode/*
-!.vscode/settings.json
+!.vscode/sample.settings.json
 !.vscode/tasks.json
-!.vscode/launch.json
+!.vscode/sample.launch.json
 !.vscode/extensions.json
 
 # CodeRush

.vscode/sample.launch.json

@@ -0,0 +1,29 @@
+{
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "type": "node",
+      "request": "launch",
+      "name": "api start",
+      "outputCapture": "std",
+      "skipFiles": ["<node_internals>/**"],
+      "program": "${workspaceFolder}",
+      "cwd": "${workspaceRoot}",
+      "envFile": "${workspaceFolder}/.env"
+    },
+    {
+      "type": "node",
+      "request": "launch",
+      "name": "api watch",
+      "runtimeExecutable": "npm",
+      "runtimeArgs": ["run", "start:watch"],
+      "restart": true,
+      "console": "integratedTerminal",
+      "internalConsoleOptions": "neverOpen",
+      "cwd": "${workspaceRoot}",
+      "outputCapture": "std",
+      "skipFiles": ["<node_internals>/**"],
+      "envFile": "${workspaceFolder}/.env"
+    }
+  ]
+}

README.md

@@ -60,6 +60,15 @@ Puis lancer les commandes suivantes :
 - `npm run db:reset` -> reset de la base `API_DATABASE` contenant les requêtes et les utilisateurs
 - `npm run start` -> démarrage du serveur Node
 
+### Liste des API
+
+Vous pouvez trouver la liste des API disponibles via la documentation OpenAPI et Swagger
+
+- Interface : <http://localhost:3000/documentation>
+  - Utile pour parcourir et explorer les API
+- Mode brut <http://localhost:3000/swagger.json>
+  - Utile pour les automatisation et les import dans vos outils de tests type Postman
+
 ### Tests autos
 
 - `npm run test`
@@ -185,7 +194,6 @@ Il s'utilise sur un container Scalingo de la manière suivante :
 scalingo -a <nom-application-scalingo> run --file ./my_awesome_queries.csv "node build/scripts/prod/add-queries-from-csv.js --file /tmp/uploads/my_awesome_queries.csv"
 ```
 
-
 Le script est assorti d'une option `--run` laquelle permet de réaliser et de persister l'insertion des requêtes.
 
 ```bash
@@ -201,6 +209,7 @@ Il est réalisé en ajoutant un enregistrement dans la tables Users en BDD à l'
 ```bash
 scalingo --app <nom-application-scalingo> run "node build/scripts/prod/add-user.js --username <userName> --label <userLabel> --password <userPassword>"
 ```
+
 En fonction de l'environnement, il peut s'avérer nécessaire de préciser `--region osc-secnum-fr1`
 
 ## Utilisation de l'API

lib/application/authentication/index.ts

@@ -1,6 +1,7 @@
 import type { Server } from '@hapi/hapi';
 import Joi from 'joi';
 
+import { SEED_PARAMETERS } from '../../common/db/seeds/seed.js';
 import { checkIfUserIsBlocked } from '../security-pre-handlers.js';
 import { authenticate } from './authentication.js';
 
@@ -13,8 +14,8 @@ const register = async function (server: Server) {
         auth: false,
         validate: {
           payload: Joi.object({
-            username: Joi.string().required(),
-            password: Joi.string().required(),
+            username: Joi.string().required().example(SEED_PARAMETERS.REF_ACADEMY_USER),
+            password: Joi.string().required().example(SEED_PARAMETERS.REF_ACADEMY_USER_PASSWORD),
           }).label('AuthenticationPayload'),
         },
         pre: [{ method: checkIfUserIsBlocked }],

lib/application/query/index.ts

@@ -1,6 +1,7 @@
 import type { Server } from '@hapi/hapi';
 import Joi from 'joi';
 
+import { SEED_PARAMETERS } from '../../common/db/seeds/seed.js';
 import { execute } from './query.js';
 
 const register = async function (server: Server) {
@@ -11,12 +12,12 @@ const register = async function (server: Server) {
       options: {
         validate: {
           payload: Joi.object({
-            queryId: Joi.string().uuid().required(),
+            queryId: Joi.string().uuid().required().example(SEED_PARAMETERS.REF_ACADEMY_QUERY_ID),
             params: Joi.array()
               .items(
                 Joi.object({
-                  name: Joi.string().required(),
-                  value: Joi.any().required(),
+                  name: Joi.string().required().example(SEED_PARAMETERS.REF_ACADEMY_PARAM_NAME),
+                  value: Joi.any().required().example([SEED_PARAMETERS.REF_ACADEMY_PARAM_VALUE]),
                 }).label('QueryParameter'),
               )
               .required()

lib/common/db/seeds/seed.js

@@ -5,60 +5,65 @@ function _getNumber(numberAsString, defaultValue) {
   const number = Number.parseInt(numberAsString, 10);
   return Number.isNaN(number) ? defaultValue : number;
 }
-const seed = async function (knex) {
+
+export const SEED_PARAMETERS = {
+  REF_ACADEMY_QUERY_ID: '123-456-789-abc-def',
+  REF_ACADEMY_USER: 'dev',
+  REF_ACADEMY_USER_PASSWORD: 'LeMotDePasseQueL\'UtilisateurUtiliseraitDeSonPointDeVue',
+  REF_ACADEMY_PARAM_NAME: 'id_list',
+  REF_ACADEMY_PARAM_VALUE: 2,
+};
+
+export const seed = async function (knex) {
   await knex('catalog_queries').insert({
     name: 'Nombre d\'académies',
     sql_query: 'SELECT COUNT(*) FROM data_ref_academies',
     id: '1b7291d4-ac51-46d2-97f1-f5f304100a29',
     created_at: new Date('2021-10-29T03:04:00Z'),
   });
 
-  const refAcademiesQueryId = 'b1e20492-8775-47f3-926d-3729ee2b836d';
-
   await knex('catalog_queries').insert({
     name: 'Académies filtrées par liste d\'id',
     sql_query:
       'SELECT id, nom, region, departements FROM data_ref_academies WHERE id = any({{ id_list }})',
-    id: refAcademiesQueryId,
+    id: SEED_PARAMETERS.REF_ACADEMY_QUERY_ID,
     created_at: new Date('2022-05-14T13:24:00Z'),
   });
   await knex('catalog_query_params').insert({
     id: 1,
-    catalog_query_id: refAcademiesQueryId,
-    name: 'id_list',
+    catalog_query_id: SEED_PARAMETERS.REF_ACADEMY_QUERY_ID,
+    name: SEED_PARAMETERS.REF_ACADEMY_PARAM_NAME,
     type: 'int-array',
     mandatory: true,
   });
 
   const hashedPassword = await bcrypt.hash(
-    'LeMotDePasseQueL\'UtilisateurUtiliseraitDeSonPointDeVue',
+    SEED_PARAMETERS.REF_ACADEMY_USER_PASSWORD,
     _getNumber(env.BCRYPT_NUMBER_OF_SALT_ROUNDS, 10),
   );
 
   const userId = '456f9d47-39a7-4de6-ada2-e47662b79bf3';
   await knex('users').insert({
     id: userId,
-    username: 'dev',
+    username: SEED_PARAMETERS.REF_ACADEMY_USER,
     label: 'Utilisateur de test',
     hashed_password: hashedPassword,
     created_at: new Date('2021-10-29T03:04:00Z'),
   });
 
   await knex('query_access').insert({
     user_id: userId,
-    query_id: refAcademiesQueryId,
+    query_id: SEED_PARAMETERS.REF_ACADEMY_QUERY_ID,
   });
 
   await knex('query_param_access').insert({
     user_id: userId,
     query_param_id: 1,
-    value: '2',
+    value: `${SEED_PARAMETERS.REF_ACADEMY_PARAM_VALUE}`,
   });
   await knex('query_param_access').insert({
     user_id: userId,
     query_param_id: 1,
     value: '4',
   });
 };
-
-export { seed };

lib/infrastructure/plugins/swagger.ts

@@ -1,22 +1,28 @@
 import HapiSwagger from 'hapi-swagger';
-
 import packageJson from '../../../package.json' with { type: 'json' };
 
-export const swaggerPlugin = {
-  plugin: HapiSwagger,
-  options: {
-    info: {
-      title: 'API Data Documentation',
-      version: packageJson.version,
-    },
-    securityDefinitions: {
-      Bearer: {
-        'type': 'apiKey',
-        'name': 'Authorization',
-        'in': 'header',
-        'x-keyPrefix': 'Bearer ',
-      },
+const swaggerOptions: HapiSwagger.RegisterOptions = {
+  OAS: 'v3.0',
+  uiOptions: {
+    url: '/openapi.json',
+  },
+  info: {
+    title: 'API Data Documentation',
+    version: packageJson.version,
+  },
+  securityDefinitions: {
+    bearerAuth: {
+      name: 'Authorization',
+      scheme: 'Bearer',
+      in: 'header',
+      description: 'Example: Bearer eyJ...z',
+      type: 'apiKey',
     },
-    security: [{ Bearer: [] }],
   },
+  security: [{ bearerAuth: [], jwt: [] }],
+};
+
+export const swaggerPlugin = {
+  plugin: HapiSwagger,
+  options: swaggerOptions,
 };

package.json

@@ -29,7 +29,7 @@
     "preinstall": "npx check-engine",
     "start": "tsx ./lib/index.ts",
     "start:prod": "npm run build && node ./build/lib",
-    "start:watch": "nodemon tsx ./lib/index.ts",
+    "start:watch": "tsx --watch  ./lib/index.ts",
     "test": "NODE_ENV=test npm run db:prepare && npm run test:api",
     "test:api": "for testType in 'unit' 'integration' 'acceptance'; do npm run test:api:$testType || status=1 ; done ; exit $status",
     "test:api:path": "NODE_ENV=test mocha --config .mocharc.json --exit --recursive --reporter=${MOCHA_REPORTER:-dot}",