From 544d13fac55768cdb4c60a4d45b20eff22d773e5 Mon Sep 17 00:00:00 2001 From: Gabriel Rosa Date: Thu, 16 Feb 2023 17:01:49 -0300 Subject: [PATCH] FIX: readme improved --- README.md | 191 +++++++++++++++++++++++++++++++------------------- docsfera.json | 25 ++++++- package.json | 10 +-- 3 files changed, 148 insertions(+), 78 deletions(-) diff --git a/README.md b/README.md index ccb4f5b..f5ed2ae 100644 --- a/README.md +++ b/README.md @@ -1,67 +1,98 @@

-

+

# Maestro + Maestro is the Dadosfera's gateway, it's responsible for the communication between the frontend application and Dadosfera's microservices. ## 🚀 Starting + These instructions will allow you to get a working copy of the project on your local machine for development and testing purposes. ### 📋 Requirements + - [NodeJS v18.3.0 LTS / NPM v8.11](https://nodejs.org/pt-br/download/) (you can opt to use [NVM](https://github.com/nvm-sh/nvm) to easily manage node versions) - Request access to AWS Console dev account for **all services** (avoid gradually asking for each needed service. it will slow down your development cycle) - - Create your Access Key on the "Security credentials" menu - - Set the Access Key on your local development machine + - Create your Access Key on the "Security credentials" menu + - Set the Access Key on your local development machine - Request access to the dev, stg and prd VPNs ### 🔧 Installation -- Clone the repository - - SSH - ``` - git clone git@github.com:dadosfera/maestro.git - ``` - or - - HTTPS - ``` - git clone https://github.com/dadosfera/maestro.git - ``` +- Clone the repository + + - SSH + + ``` + git clone git@github.com:dadosfera/maestro.git + ``` + + or + + - HTTPS + ``` + git clone https://github.com/dadosfera/maestro.git + ``` - Select the correct node version (optional, only if using [NVM](https://github.com/nvm-sh/nvm)): - ```sh - nvm use - ``` + + ```sh + nvm use + ``` - Install the project dependencies: - ```sh - npm i - ``` + + ```sh + npm i + ``` - Setup the following enviroment variables: - ``` - ENV= - DUC_URL= - INFACTORY_URL= - OTFACTORY_URL= - PIFACTORY_URL= - SM_OAUTH_PATH= - ``` + + ``` + ENV= + DUC_URL= + INFACTORY_URL= + OTFACTORY_URL= + PIFACTORY_URL= + SM_OAUTH_PATH= + ``` - Start the server: - ```sh - # dev mode - npm run start:dev - # or in debug mode - npm run start:debug - ``` - The service should start successfully. + ```sh + # dev mode + npm run start:dev + + # or in debug mode + npm run start:debug + ``` + + The service should start successfully. + +## 📄 Documentation + +NestJs makes it easy to document each route using decorators on all requests and responses properties. It automatically generates a swagger for given information and provides a route to access it http://localhost:3333/api. +For more info check the [official documentation](https://docs.nestjs.com/openapi/introduction). + +### - Multiple documentations + +We are currently generating **2 different** documentations: Internal and External. + +All routes that have the decorator `@ApiInternalOnly()` will not be visible on the **External** API swagger. + +- When you start the application with `npm run start` it will serve and generate the swagger JSON of the **External** API +- When you start the application with `npm run start:internal` it will serve and generate the swagger JSON of the **Internal** API +- When you run `npm run docs` it will generate the swagger JSON of both **Internal** and **External** API, and save them to `docsfera.json` and `docsfera.external.json` respectively; + +It is important to run `npm run docs` before every deploy so we can always have the most updated docs published. ## Authentication decorators + Maestro have utilities to ease the user authentication on every controller and route. The following decorators are available: ### `@Authenticated` + If the user must be authenticated to make request, we can use the `@Authenticated` decorator in the controller or route, as needed. ```ts @@ -106,6 +137,7 @@ class FooController { ``` ### `@RequireAllPermissions` + This decorator requires that **all permissions** listed are granted to the requesting user. ```ts @@ -125,6 +157,7 @@ class FooController { ``` ### `@RequireSomePermission` + In the following case, the user is required to have **at least one** listed permission. ```ts @@ -144,9 +177,11 @@ class FooController { ``` ### `@AuthenticateCondition` + If a more complicated authentication check needs to be done, we can use the `@AuthenticateCondition` decorator to define it. The custom function must return `true` to authenticate the request. In the following example: + - all routes on the `FooController` controller can only be requested from localhost - `POST /foo/bar` can only be requested from localhost **and** by users from customer id `111...eef` @@ -166,7 +201,10 @@ class FooController { @Post('bar') // allow requests only from a specific customer - @AuthenticateCondition((request: Request, user: RequestUser) => user.customer_id === '1113e943-2187-4fdd-9c2c-54338fedaeef') + @AuthenticateCondition( + (request: Request, user: RequestUser) => + user.customer_id === '1113e943-2187-4fdd-9c2c-54338fedaeef', + ) async postBar() { /* ... */ } @@ -174,51 +212,55 @@ class FooController { ``` ### Note on authentication decorators + - The old authentication method placed the user data in the `request.body.info` field, this imposes certain issues regarding the request body because this data should be from the frontend without any modification by Maestro. Now this usage is ⚠️ **DEPRECATED** ⚠️. We are working to migrate to the `@User` parameter decorator. The old method is working while the migration is in progress. -- Authentication decorators can be used together and all of them **must** pass to the request be authenticated, but in the general case you don't need to (*and wouldn't like to...*) use all of them together, as you can code all of the authentication logic in the `@AuthenticateCondition` decorator. +- Authentication decorators can be used together and all of them **must** pass to the request be authenticated, but in the general case you don't need to (_and wouldn't like to..._) use all of them together, as you can code all of the authentication logic in the `@AuthenticateCondition` decorator. - ```ts - import { - RequireAllPermissions, - RequireSomePermission, - AuthenticateCondition, - } from '../../authentication/authentication.decorator'; - import { PERMISSIONS } from '../../authentication/permissions.enum'; - import { Waa, Baz } from './authenticationFunctions' + ```ts + import { + RequireAllPermissions, + RequireSomePermission, + AuthenticateCondition, + } from '../../authentication/authentication.decorator'; + import { PERMISSIONS } from '../../authentication/permissions.enum'; + import { Waa, Baz } from './authenticationFunctions'; - @Controller('foo') - @RequireAllPermissions(Permissions.FOO.USE, Permissions.FOO.REQUEST) - @RequireSomePermission(Permissions.FOO.MANAGE, Permissions.FOO.ADMIN) - @AuthenticateCondition(Waa) - @AuthenticateCondition(Baz) - class FooController { + @Controller('foo') + @RequireAllPermissions(Permissions.FOO.USE, Permissions.FOO.REQUEST) + @RequireSomePermission(Permissions.FOO.MANAGE, Permissions.FOO.ADMIN) + @AuthenticateCondition(Waa) + @AuthenticateCondition(Baz) + class FooController { + /* ... */ + + @Get('bar') + async getBar() { /* ... */ - - @Get('bar') - async getBar() { - /* ... */ - } - - @Post('bar') - @RequireAllPermissions(Permissions.BAR.MANAGE, Permissions.BAR.USE, Permissions.BAR.REQUEST) - async postBar() { - /* ... */ - } } - ``` + + @Post('bar') + @RequireAllPermissions( + Permissions.BAR.MANAGE, + Permissions.BAR.USE, + Permissions.BAR.REQUEST, + ) + async postBar() { + /* ... */ + } + } + ``` - If `@RequireAllPermissions` and `@RequireSomePermission` are used with **only a single permission**, they present the **exactly same behavior**. - ```ts - // same behavior - @RequireAllPermissions(Permissions.BAR.MANAGE) - @RequireSomePermission(Permissions.BAR.MANAGE) - ``` - - + ```ts + // same behavior + @RequireAllPermissions(Permissions.BAR.MANAGE) + @RequireSomePermission(Permissions.BAR.MANAGE) + ``` ## `@User` parameter decorator + The requesting user data can be obtained using the @User parameter decorator, like in the following snippet: ```ts @@ -264,12 +306,15 @@ class UserController { ``` ## 📦 Development + ### ⌨️ Coding Style + By default, we use [ESLint](https://eslint.org/) + [Prettier](https://prettier.io/) with default settings. **We recommend using Visual Studio Code and installing the recommended extensions to ease the development process.** ### Commits pattern + Our workflow pipeline follows the conventional commits specs ([cheat sheets](https://cheatography.com/albelop/cheat-sheets/conventional-commits/)) to release versions accordingly. Format: `[optional scope]: ` @@ -277,25 +322,29 @@ Format: `[optional scope]: ` Example: `FIX: ensure Range headers adhere more closely to RFC 2616` ### Branching naming convention + - **Feature**: Any code changes for a new module or use case should be done on a feature branch. This branch is created based on the `main` branch. When all changes are done, a Pull Request/Merge Request is needed to put all of these changes back to the `main` branch. Examples: `feature/integrate-swagger`, `feature/JIRA-1234`, `feature/JIRA-1234_support-dark-theme`. - **It is recommended to use all lower caps letters and hyphen (-) to separate words unless it is a specific item name or ID. Underscore (_) could be used to separate the ID and description.** + **It is recommended to use all lower caps letters and hyphen (-) to separate words unless it is a specific item name or ID. Underscore (\_) could be used to separate the ID and description.** -- **Bug Fix**: If the code changes made from the feature branch were rejected after a release, sprint or demo, any necessary fixes after that should be done on the bugfix branch. Examples: `bugfix/more-gray-shades`, `bugfix/JIRA-1444_gray-on-blur-fix`. +- **Bug Fix**: If the code changes made from the feature branch were rejected after a release, sprint or demo, any necessary fixes after that should be done on the bugfix branch. Examples: `bugfix/more-gray-shades`, `bugfix/JIRA-1444_gray-on-blur-fix`. - **Hot Fix**: If there is a need to fix a blocker, do a temporary patch, apply a critical framework or configuration change that should be handled immediately, it should be created as a Hotfix. Examples: `hotfix/disable-endpoint-zero-day-exploit`, `hotfix/increase-scaling-threshold`. - **Experimental**: A branch for playing around. Any new feature or idea that is not part of a release or a sprint. Example: `experimental/dark-theme-support`. ### Making a Pull Request + 1. Commit your changes 2. Open the Pull Request on GitHub 3. Send Pull Request link in Microsfera Google Chat Group for review and possible approval ## 🛠️ Built with + Some technologies used in this project: - [NestJS](https://docs.nestjs.com) - Framework for building efficient and scalable NodeJS server-side applications ## ⚙️ Back-end Architecture + The architecture can be found at [this link](https://sites.google.com/dadosfera.ai/wikidoproduto/time/back-end). diff --git a/docsfera.json b/docsfera.json index a4f3757..dee5148 100644 --- a/docsfera.json +++ b/docsfera.json @@ -3415,11 +3415,32 @@ "type": "string" } }, + { + "name": "size", + "required": false, + "in": "query", + "description": "Número de registros a ser retornado", + "schema": { + "minimum": 1, + "maximum": 10000, + "type": "number" + } + }, + { + "name": "page", + "required": false, + "in": "query", + "description": "Usado para paginação, em conjunto com `size`", + "schema": { + "minimum": 1, + "type": "number" + } + }, { "name": "sort_by", "required": false, "in": "query", - "description": "Data Asset field to sort", + "description": "Campo do data asset para usar na ordenação. Padrão: `created_at` ", "schema": { "type": "string" } @@ -3428,7 +3449,7 @@ "name": "order", "required": false, "in": "query", - "description": "Tipo de ordenação - asc: crescente; desc: decrescente ", + "description": "Tipo de ordenação - `asc`: crescente; `desc`: decrescente ", "schema": { "default": "asc", "enum": [ diff --git a/package.json b/package.json index 84e105f..b829842 100644 --- a/package.json +++ b/package.json @@ -15,10 +15,10 @@ "build": "nest build", "format": "prettier --write \"src/**/*.ts\" \"test/**/*.ts\"", "start": "nest start", - "start:dev": "nest start --watch", - "start:debug": "nest start --debug --watch", - "start:kill": "export KILL_AFTER_START=1 && nest start && export KILL_AFTER_START=0", - "start:prod": "npm run build && node dist/main", + "start:dev": "export INTERNAL_SWAGGER=true && nest start --watch", + "start:debug": "npm run start:dev", + "start:prod": "node dist/main", + "docs": "export KILL_AFTER_START=1 && nest start && export INTERNAL_SWAGGER=true && nest start", "lint": "eslint \"{src,apps,libs,test}/**/*.ts\" --fix", "test": "jest", "test:watch": "jest --watch", @@ -96,4 +96,4 @@ "tsconfig-paths": "^3.14.1", "typescript": "^4.6.3" } -} +} \ No newline at end of file