docs: add all components api docs

.gitignore

@@ -1,4 +1,5 @@
 node_modules
 dist
 coverage
-.vscode
+.vscode
+globalConfig.json

package.json

@@ -8,17 +8,17 @@
     "build": "rimraf dist && tsc -p tsconfig-build.json",
     "dev": "sucrase-node src/main/server.ts",
     "check": "npm-check -s -u",
-    "test": "jest --passWithNoTests --silent --noStackTrace --runInBand",
-    "test:verbose": "jest --passWithNoTests --runInBand",
+    "test": "jest --passWithNoTests --runInBand --no-cache",
     "test:unit": "npm test -- --watch -c jest-unit-config.js",
+    "test:verbose": "jest --passWithNoTests --runInBand",
     "test:integration": "npm test -- --watch -c jest-integration-config.js",
     "test:staged": "npm test -- --findRelatedTests",
     "test:ci": "npm test -- --coverage",
     "prepare": "husky install"
   },
   "keywords": [],
   "author": "Gilberto Mossmann",
-  "license": "ISC",
+  "license": "GPL-3.0-or-later",
   "devDependencies": {
     "@shelf/jest-mongodb": "^4.1.7",
     "@types/bcrypt": "^5.0.0",
@@ -60,6 +60,9 @@
     "swagger-ui-express": "^4.6.2",
     "validator": "^13.9.0"
   },
+  "engines": {
+    "node": "16.x"
+  },
   "_moduleAliases": {
     "@": "dist"
   }

src/main/docs/components.ts

@@ -0,0 +1,19 @@
+import { apiKeyAuthSchema } from './schemas/'
+import {
+  badRequest,
+  serverError,
+  unauthorized,
+  notFound,
+  forbidden
+} from './components/'
+
+export default {
+  securitySchemes: {
+    apiKeyAuth: apiKeyAuthSchema
+  },
+  badRequest,
+  serverError,
+  unauthorized,
+  notFound,
+  forbidden
+}

src/main/docs/components/bad-request.ts

@@ -0,0 +1,10 @@
+export const badRequest = {
+  description: 'Requisição inválida',
+  content: {
+    'application/json': {
+      schema: {
+        $ref: '#/schemas/error'
+      }
+    }
+  }
+}

src/main/docs/components/forbidden.ts

@@ -0,0 +1,10 @@
+export const forbidden = {
+  description: 'Acesso negado',
+  content: {
+    'application/json': {
+      schema: {
+        $ref: '#/schemas/error'
+      }
+    }
+  }
+}

src/main/docs/components/index.ts

@@ -0,0 +1,5 @@
+export * from './bad-request'
+export * from './server-error'
+export * from './unauthorized'
+export * from './not-found'
+export * from './forbidden'

src/main/docs/components/not-found.ts

@@ -0,0 +1,3 @@
+export const notFound = {
+  description: 'API não encontrada'
+}

src/main/docs/components/server-error.ts

@@ -0,0 +1,10 @@
+export const serverError = {
+  description: 'Erro interno no servidor',
+  content: {
+    'application/json': {
+      schema: {
+        $ref: '#/schemas/error'
+      }
+    }
+  }
+}

src/main/docs/components/unauthorized.ts

@@ -0,0 +1,10 @@
+export const unauthorized = {
+  description: 'Credenciais inválidas',
+  content: {
+    'application/json': {
+      schema: {
+        $ref: '#/schemas/error'
+      }
+    }
+  }
+}

src/main/docs/index.ts

@@ -1,6 +1,6 @@
-import { loginPath } from './paths/login-path'
-import { accountSchema } from './schemas/account-schema'
-import { loginParamsSchema } from './schemas/login-params-schema'
+import paths from './paths'
+import components from './components'
+import schemas from './schemas'
 
 export default {
   openapi: '3.0.0',
@@ -14,16 +14,17 @@ export default {
     }
   },
   servers: [{
-    url: '/api'
+    url: '/api',
+    description: 'Servidor Principal'
   }],
   tags: [{
-    name: 'Login'
+    name: 'Login',
+    description: 'APIs relacionadas a Login'
+  }, {
+    name: 'Enquete',
+    description: 'APIs relacionadas a Enquete'
   }],
-  paths: {
-    '/login': loginPath
-  },
-  schemas: {
-    account: accountSchema,
-    loginParams: loginParamsSchema
-  }
+  paths,
+  schemas,
+  components
 }

src/main/docs/paths.ts

@@ -0,0 +1,13 @@
+import {
+  loginPath,
+  surveyPath,
+  signUpPath,
+  surveyResultPath
+} from './paths/'
+
+export default {
+  '/login': loginPath,
+  '/signup': signUpPath,
+  '/surveys': surveyPath,
+  '/surveys/{surveyId}/results': surveyResultPath
+}

src/main/docs/paths/index.ts

@@ -0,0 +1,4 @@
+export * from './login-path'
+export * from './survey-path'
+export * from './signup-path'
+export * from './survey-result-path'

src/main/docs/paths/login-path.ts

@@ -2,7 +2,9 @@ export const loginPath = {
   post: {
     tags: ['Login'],
     summary: 'API para autenticar usuário',
+    description: 'Essa rota pode ser executada por **qualquer usuário**',
     requestBody: {
+      required: true,
       content: {
         'application/json': {
           schema: {
@@ -21,6 +23,18 @@ export const loginPath = {
             }
           }
         }
+      },
+      400: {
+        $ref: '#/components/badRequest'
+      },
+      401: {
+        $ref: '#/components/unauthorized'
+      },
+      404: {
+        $ref: '#/components/notFound'
+      },
+      500: {
+        $ref: '#/components/serverError'
       }
     }
   }

src/main/docs/paths/signup-path.ts

@@ -0,0 +1,41 @@
+export const signUpPath = {
+  post: {
+    tags: ['Login'],
+    summary: 'API para criar conta de um usuário',
+    description: 'Essa rota pode ser executada por **qualquer usuário**',
+    requestBody: {
+      required: true,
+      content: {
+        'application/json': {
+          schema: {
+            $ref: '#/schemas/signUpParams'
+          }
+        }
+      }
+    },
+    responses: {
+      200: {
+        description: 'Sucesso',
+        content: {
+          'application/json': {
+            schema: {
+              $ref: '#/schemas/account'
+            }
+          }
+        }
+      },
+      400: {
+        $ref: '#/components/badRequest'
+      },
+      403: {
+        $ref: '#/components/forbidden'
+      },
+      404: {
+        $ref: '#/components/notFound'
+      },
+      500: {
+        $ref: '#/components/serverError'
+      }
+    }
+  }
+}

src/main/docs/paths/survey-path.ts

@@ -0,0 +1,66 @@
+export const surveyPath = {
+  get: {
+    security: [{
+      apiKeyAuth: []
+    }],
+    tags: ['Enquete'],
+    summary: 'API para listar todas as enquetes',
+    description: 'Essa rota só pode ser executada por **usuários autenticados**',
+    responses: {
+      200: {
+        description: 'Sucesso',
+        content: {
+          'application/json': {
+            schema: {
+              $ref: '#/schemas/surveys'
+            }
+          }
+        }
+      },
+      204: {
+        description: 'Sucesso, mas sem dados para exibir'
+      },
+      403: {
+        $ref: '#/components/forbidden'
+      },
+      404: {
+        $ref: '#/components/notFound'
+      },
+      500: {
+        $ref: '#/components/serverError'
+      }
+    }
+  },
+  post: {
+    security: [{
+      apiKeyAuth: []
+    }],
+    tags: ['Enquete'],
+    summary: 'API para criar uma enquete',
+    description: 'Essa rota só pode ser executada por **administradores**',
+    requestBody: {
+      required: true,
+      content: {
+        'application/json': {
+          schema: {
+            $ref: '#/schemas/addSurveyParams'
+          }
+        }
+      }
+    },
+    responses: {
+      204: {
+        description: 'Sucesso, mas sem dados para exibir'
+      },
+      403: {
+        $ref: '#/components/forbidden'
+      },
+      404: {
+        $ref: '#/components/notFound'
+      },
+      500: {
+        $ref: '#/components/serverError'
+      }
+    }
+  }
+}

src/main/docs/paths/survey-result-path.ts

@@ -0,0 +1,88 @@
+export const surveyResultPath = {
+  put: {
+    security: [{
+      apiKeyAuth: []
+    }],
+    tags: ['Enquete'],
+    summary: 'API para criar a resposta de uma enquete',
+    description: 'Essa rota só pode ser executada por **usuários autenticados**',
+    parameters: [{
+      in: 'path',
+      name: 'surveyId',
+      description: 'ID da enquete a ser respondida',
+      required: true,
+      schema: {
+        type: 'string'
+      }
+    }],
+    requestBody: {
+      required: true,
+      content: {
+        'application/json': {
+          schema: {
+            $ref: '#/schemas/saveSurveyParams'
+          }
+        }
+      }
+    },
+    responses: {
+      200: {
+        description: 'Sucesso',
+        content: {
+          'application/json': {
+            schema: {
+              $ref: '#/schemas/surveyResult'
+            }
+          }
+        }
+      },
+      403: {
+        $ref: '#/components/forbidden'
+      },
+      404: {
+        $ref: '#/components/notFound'
+      },
+      500: {
+        $ref: '#/components/serverError'
+      }
+    }
+  },
+  get: {
+    security: [{
+      apiKeyAuth: []
+    }],
+    tags: ['Enquete'],
+    summary: 'API para consultar o resultado de uma enquete',
+    description: 'Essa rota só pode ser executada por **usuários autenticados**',
+    parameters: [{
+      in: 'path',
+      name: 'surveyId',
+      description: 'ID da enquete a ser respondida',
+      required: true,
+      schema: {
+        type: 'string'
+      }
+    }],
+    responses: {
+      200: {
+        description: 'Sucesso',
+        content: {
+          'application/json': {
+            schema: {
+              $ref: '#/schemas/surveyResult'
+            }
+          }
+        }
+      },
+      403: {
+        $ref: '#/components/forbidden'
+      },
+      404: {
+        $ref: '#/components/notFound'
+      },
+      500: {
+        $ref: '#/components/serverError'
+      }
+    }
+  }
+}