From 1be8370d486db0be3589f92165d96c1f171bd084 Mon Sep 17 00:00:00 2001 From: Henrique Quenino Date: Wed, 11 Oct 2023 00:21:04 -0300 Subject: [PATCH 1/6] =?UTF-8?q?defini=C3=A7=C3=A3o=20de=20rotas=20da=20api?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/api.md | 188 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 188 insertions(+) create mode 100644 docs/api.md diff --git a/docs/api.md b/docs/api.md new file mode 100644 index 00000000..1da92902 --- /dev/null +++ b/docs/api.md @@ -0,0 +1,188 @@ +# Definição de rotas + +## Rotas do web site "Sua Grade UnB" + +### Autenticação do Google + +**Método HTTP:** `GET` +**Rota:** `/auth/google` + +Essa rota permite ao usuário fazer login com sua conta do Google. + +**Response:** + +A resposta conterá informações de autenticação bem-sucedida, incluindo um token de autenticação. + +```json +body: { + "access_token": "token_de_acesso" +} +``` + +- `"access_token"`: O token de acesso que permite ao usuário autenticado acessar recursos protegidos. + +### Consulta da Grade de Matérias + +**Método HTTP:** `GET` +**Rota:** `/schedules` + +Após a seleção das matérias, o usuário pode acessar esta rota para visualizar a grade de matérias gerada pela API da faculdade. + +**Requests:** + +```json +headers = { + "Authorization": "Token" +} +``` + +**Response:** + +```json +{ + "schedules": { + "id": 123, + "name": "Grade 1", + "date": "2021-01-01", + "schedule": [ + { + "day": "Segunda-feira", + "courses": [ + { + "name": "Cálculo 1", + "time": "2M34" + }, + { + "name": "Fisica 1", + "time": "2T23" + } + ] + }, + { + "day": "Terça-feira", + "courses": [ + { + "name": "Cálculo 1", + "time": "3M34" + }, + { + "name": "Fisica 1", + "time": "3T23" + } + ] + } + ] + } +} +``` + +- `"schedule"`: Uma lista de objetos representando a grade de matérias por dia. Cada objeto possui um campo `"day"` e uma lista de cursos `"courses"` para esse dia. + +### Visualização de Perfil + +**Método HTTP:** `GET` +**Rota:** `/profile` + +Esta rota permite ao usuário visualizar seu perfil, incluindo informações pessoais e configurações. + +**Requests:** + +```json +headers = { + "Authorization": "Token" +} +``` + +**Response:** + +```json +{ + "info": { + "foto": "link", + "nome": "Nome do Usuário", + "email": "email_do_cliente@example.com" + } +} +``` + +### Logout + +**Método HTTP:** `GET` +**Rota:** `/logout` + +Esta rota permite ao usuário fazer logout de sua conta no site. + +**Requests:** + +```json +headers = { + "Authorization": "Token" +} +``` + +### Montagem de Grade + +**Método HTTP:** `POST` +**Rota:** `/schedules/create` + +Esta rota permite ao usuário realizar uma montagem de grade, selecionando especificamente as matérias e horários desejados. + +**Response:** + +```json +{ + "mode": "manual | automatic", + "preference": "M", + + "courses": [ + { + "name": "Tópicos Especiais em Engenharia de Software", + "times": [ + ["23M34","Segunda e Terça - 10:00 a 12:00"], + ["2T23","Segunda - 14:00 a 16:00"] + ], + "professors": ["BRUNO CESAR RIBAS", "EDSON ALVES DA COSTA JUNIOR"] + }, + { + "name": "Fisica 1", + "times": [ + ["45M34","Quarta e Quinta - 10:00 a 12:00"], + ["6T23","Sexta - 14:00 a 16:00"] + ], + "professors": ["LUIZA YOKO", "RAFAEL MORGADO DA SILVA"] + + } + ] +} +``` + +- `"courses"`: Uma lista de objetos representando as matérias selecionadas manualmente. Cada objeto contém o `"name"` (nome da matéria), `"day"` (dia da semana) e `"time"` (horário). + +- `"preference"`: A preferência de horário escolhida pelo usuário (por exemplo, "M" para manhã, "T" para tarde, "N" para noite). + +- `"professors"`: Uma lista de nomes de professores preferidos escolhidos pelo usuário. + +### Deleção de Grade Salva + +**Método HTTP:** `DELETE` +**Rota:** `/schedules` + +O usuário pode usar esta rota para excluir uma grade de matérias salva anteriormente, caso deseje remover uma configuração específica. + +**Requests:** + +```json +headers = { + "Authorization": "Token" +} +``` + +**Response:** + +```json +{ + "schedule_id": 123 +} +``` + +- `"schedule_id"`: O identificador único da grade de matérias a ser excluída. From c5827420ef7a8bebd18ea31ad615e4d502641aa5 Mon Sep 17 00:00:00 2001 From: Henrique Quenino Date: Wed, 11 Oct 2023 21:10:50 -0300 Subject: [PATCH 2/6] Inseridas rotas da api que estavam faltando --- docs/api.md | 117 ++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 114 insertions(+), 3 deletions(-) diff --git a/docs/api.md b/docs/api.md index 1da92902..37dcd9ae 100644 --- a/docs/api.md +++ b/docs/api.md @@ -26,7 +26,8 @@ body: { **Método HTTP:** `GET` **Rota:** `/schedules` -Após a seleção das matérias, o usuário pode acessar esta rota para visualizar a grade de matérias gerada pela API da faculdade. +Esta rota permite ao usuário visualizar uma grade de matérias criada. + **Requests:** @@ -77,6 +78,13 @@ headers = { ``` - `"schedule"`: Uma lista de objetos representando a grade de matérias por dia. Cada objeto possui um campo `"day"` e uma lista de cursos `"courses"` para esse dia. +- `"courses"`: Uma lista de objetos representando as matérias selecionadas manualmente. Cada objeto contém o `"name"` (nome da matéria) e `"time"` (horário). +- `"date"`: A data em que a grade de matérias foi criada. +- `"name"`: O nome da grade da matéria. +- `"id"`: O identificador único da grade de matérias. +- `"day"`: O dia da semana em que é ministrada a aula. +- `"time"`: Código que fornece o horário em que é ministrada a aula e bem o dia da semana em que acontece. + ### Visualização de Perfil @@ -125,7 +133,7 @@ headers = { **Método HTTP:** `POST` **Rota:** `/schedules/create` -Esta rota permite ao usuário realizar uma montagem de grade, selecionando especificamente as matérias e horários desejados. +Esta rota permite ao usuário criar uma grade de matérias, selecionando manualmente as matérias e horários ou deixando o sistema escolher automaticamente por preferencias determinadas pelo usuário. **Response:** @@ -157,11 +165,114 @@ Esta rota permite ao usuário realizar uma montagem de grade, selecionando espec ``` - `"courses"`: Uma lista de objetos representando as matérias selecionadas manualmente. Cada objeto contém o `"name"` (nome da matéria), `"day"` (dia da semana) e `"time"` (horário). - - `"preference"`: A preferência de horário escolhida pelo usuário (por exemplo, "M" para manhã, "T" para tarde, "N" para noite). +- `"professors"`: Uma lista de nomes de professores preferidos escolhidos pelo usuário. +- `"mode"`: O modo de montagem da grade de matérias, que pode ser manual ou automático. +- `"schedule"`: Uma lista de objetos representando a grade de matérias por dia. Cada objeto possui um campo `"day"` e uma lista de cursos `"courses"` para esse dia. +- `"courses"`: Uma lista de objetos representando as matérias selecionadas manualmente. Cada objeto contém o `"name"` (nome da matéria) e `"time"` (horário). + + +### Update de Grade + +**Método HTTP:** `PUT` Rota: `/schedules/update` + +Esta rota permite ao usuário atualizar uma grade de matérias salva anteriormente, caso deseje alterar uma configuração específica. + +**Requests:** + +```json +headers = { + "Authorization": "Token" +} +``` +**Response:** +```json +body: { + "schedule_id": 123, + "mode": "manual", + "courses": [ + { + "name": "Tópicos Especiais em Engenharia de Software", + "times": [ + ["23M34","Segunda e Terça - 10:00 a 12:00"], + ["2T23","Segunda - 14:00 a 16:00"] + ], + "professors": ["BRUNO CESAR RIBAS", "EDSON ALVES DA COSTA JUNIOR"] + }, + { + "name": "Fisica 1", + "times": [ + ["45M34","Quarta e Quinta - 10:00 a 12:00"], + ["6T23","Sexta - 14:00 a 16:00"] + ], + "professors": ["LUIZA YOKO", "RAFAEL MORGADO DA SILVA"] + + } + ] +} +``` +- `"schedule_id"`: O identificador único da grade de matérias a ser atualizada. +- `"courses"`: Uma lista de objetos representando as matérias selecionadas manualmente. Cada objeto contém o `"name"` (nome da matéria), `"day"` (dia da semana) e `"time"` (horário). - `"professors"`: Uma lista de nomes de professores preferidos escolhidos pelo usuário. +**Response:** + +A resposta confirmará a atualização bem-sucedida da grade de matérias. + +```json +{ + "message": "Grade atualizada com sucesso." +} +``` + +## Busca por Matéria + +**Método HTTP:** `GET` +**Rota:** `/courses/search` + +Esta rota permite ao usuário pesquisar e encontrar informações detalhadas sobre uma matéria específica na universidade. + +**Request:** + +```json +query = "Cálculo 1" +``` + +- `query`: A consulta que o usuário deseja fazer para encontrar informações sobre uma matéria específica. + +**Response:** + +A resposta incluirá informações detalhadas sobre a matéria procurada. + +```json +{ + "course_name": "Cálculo 1", + "course_code": "MAT101", + "description": "Este curso aborda os conceitos fundamentais de cálculo, incluindo limites, derivadas e integrais.", + "professors": ["LUIZA YOKO", "RICARDO FRAGELLI"], + "schedule": [ + { + "day": "Segunda-feira", + "time": "2M34" + }, + { + "day": "Terça-feira", + "time": "2T23" + } + ] +} +``` + +- `"course_name"`: O nome da matéria pesquisada. + +- `"course_code"`: O código da matéria na universidade. + +- `"description"`: Uma breve descrição do conteúdo do curso. + +- `"professors"`: Uma lista de professores que ministram o curso. + +- `"schedule"`: Um horário típico de aulas para a matéria, incluindo os dias da semana e horários. ### Deleção de Grade Salva **Método HTTP:** `DELETE` From e4650dc3dd8d685409d4c1a8781e6bd6acaf7839 Mon Sep 17 00:00:00 2001 From: Henrique Quenino Date: Wed, 18 Oct 2023 14:17:56 -0300 Subject: [PATCH 3/6] Rearranjo nas respostas das consultas de grades --- docs/api.md | 141 ++++++++++++++++++++++++++++++++++++++++------------ 1 file changed, 110 insertions(+), 31 deletions(-) diff --git a/docs/api.md b/docs/api.md index 37dcd9ae..253381a0 100644 --- a/docs/api.md +++ b/docs/api.md @@ -13,10 +13,26 @@ Essa rota permite ao usuário fazer login com sua conta do Google. A resposta conterá informações de autenticação bem-sucedida, incluindo um token de autenticação. -```json -body: { - "access_token": "token_de_acesso" +```js +{ + "routes": [ + { + "path": "/auth/google", + "method": "GET", + "description": "Iniciar autenticação do Google OAuth2.", + "scope": ["profile", "email"] + }, + { + "path": "/auth/google/callback", + "method": "GET", + "description": "Rota de retorno de chamada após a autenticação do Google OAuth2. Recebe o token de acesso do Google.", + "successRedirect": "/profile", + "failureRedirect": "/login", + "receivesAccessToken": true + }, + ], } + ``` - `"access_token"`: O token de acesso que permite ao usuário autenticado acessar recursos protegidos. @@ -26,12 +42,11 @@ body: { **Método HTTP:** `GET` **Rota:** `/schedules` -Esta rota permite ao usuário visualizar uma grade de matérias criada. - +Esta rota permite ao usuário visualizar várias grades de matérias criadas. **Requests:** -```json +```js headers = { "Authorization": "Token" } @@ -39,9 +54,9 @@ headers = { **Response:** -```json +```js { - "schedules": { + "schedule 1": { "id": 123, "name": "Grade 1", "date": "2021-01-01", @@ -52,10 +67,16 @@ headers = { { "name": "Cálculo 1", "time": "2M34" + "code": "MAT101" + "teacher": ["LUIZA YOKO"] + "classroom": "S1" }, { "name": "Fisica 1", "time": "2T23" + "code": "FIS101" + "teacher": ["RAFAEL MORGADO DA SILVA"] + "classroom": "S2" } ] }, @@ -65,10 +86,61 @@ headers = { { "name": "Cálculo 1", "time": "3M34" + "code": "MAT101" + "teacher": ["LUIZA YOKO"] + "classroom": "S1" }, { "name": "Fisica 1", "time": "3T23" + "code": "FIS101" + "teacher": ["RAFAEL MORGADO DA SILVA"] + "classroom": "S2" + } + ] + } + ] + } + "schedule 2": { + "id": 456, + "name": "Grade 2", + "date": "2021-01-01", + "schedule": [ + { + "day": "Quarta-feira", + "courses": [ + { + "name": "Cálculo 1", + "time": "2M34" + "code": "MAT102" + "teacher": ["Ricardo Fragelli"] + "classroom": "S1" + }, + { + "name": "Fisica 1", + "time": "2T23" + "code": "FIS104" + "teacher": ["RAFAEL MORGADO DA SILVA"] + "classroom": "S2" + } + ] + }, + { + "day": "Sexta-feira", + "courses": [ + { + "name": "Cálculo 1", + "time": "3M34" + "code": "MAT102" + "teacher": ["Ricardo Fragelli"] + "classroom": "S1" + }, + { + "name": "Fisica 1", + "time": "3T23" + "code": "FIS104" + "teacher": ["RAFAEL MORGADO DA SILVA"] + "classroom": "S2" } ] } @@ -78,12 +150,14 @@ headers = { ``` - `"schedule"`: Uma lista de objetos representando a grade de matérias por dia. Cada objeto possui um campo `"day"` e uma lista de cursos `"courses"` para esse dia. -- `"courses"`: Uma lista de objetos representando as matérias selecionadas manualmente. Cada objeto contém o `"name"` (nome da matéria) e `"time"` (horário). +- `"courses"`: Uma lista de objetos representando as matérias selecionadas manualmente. Cada objeto contém o `"name"` (nome da matéria), `"time"` (horário) e `"teacher"` (professor) e `"classroom"` (sala de aula). - `"date"`: A data em que a grade de matérias foi criada. - `"name"`: O nome da grade da matéria. - `"id"`: O identificador único da grade de matérias. - `"day"`: O dia da semana em que é ministrada a aula. - `"time"`: Código que fornece o horário em que é ministrada a aula e bem o dia da semana em que acontece. +- `"teacher"`: O nome do professor que ministra a aula. +- `"classroom"`: O código da sala de aula em que é ministrada a aula. ### Visualização de Perfil @@ -95,7 +169,7 @@ Esta rota permite ao usuário visualizar seu perfil, incluindo informações pes **Requests:** -```json +```js headers = { "Authorization": "Token" } @@ -103,15 +177,18 @@ headers = { **Response:** -```json +```js { "info": { - "foto": "link", - "nome": "Nome do Usuário", - "email": "email_do_cliente@example.com" + "photo": "link", + "name": "Client name", + "email": "client@email.com" } } ``` +- `"photo"`: A foto de perfil do usuário. +- `"name"`: O nome do usuário. +- `"email"`: O email do usuário. ### Logout @@ -122,7 +199,7 @@ Esta rota permite ao usuário fazer logout de sua conta no site. **Requests:** -```json +```js headers = { "Authorization": "Token" } @@ -137,7 +214,7 @@ Esta rota permite ao usuário criar uma grade de matérias, selecionando manualm **Response:** -```json +```js { "mode": "manual | automatic", "preference": "M", @@ -145,6 +222,7 @@ Esta rota permite ao usuário criar uma grade de matérias, selecionando manualm "courses": [ { "name": "Tópicos Especiais em Engenharia de Software", + "code": "ESW101", "times": [ ["23M34","Segunda e Terça - 10:00 a 12:00"], ["2T23","Segunda - 14:00 a 16:00"] @@ -153,6 +231,7 @@ Esta rota permite ao usuário criar uma grade de matérias, selecionando manualm }, { "name": "Fisica 1", + "code": "FIS101", "times": [ ["45M34","Quarta e Quinta - 10:00 a 12:00"], ["6T23","Sexta - 14:00 a 16:00"] @@ -163,14 +242,13 @@ Esta rota permite ao usuário criar uma grade de matérias, selecionando manualm ] } ``` - -- `"courses"`: Uma lista de objetos representando as matérias selecionadas manualmente. Cada objeto contém o `"name"` (nome da matéria), `"day"` (dia da semana) e `"time"` (horário). +- `"mode"`: O modo de montagem da grade de matérias, que pode ser manual ou automático. - `"preference"`: A preferência de horário escolhida pelo usuário (por exemplo, "M" para manhã, "T" para tarde, "N" para noite). +- `"courses"`: Uma lista de objetos representando as matérias selecionadas manualmente. Cada objeto contém o `"name"` (nome da matéria), `"code"` (código da disciplina), `"day"` (dia da semana) e `"time"` (horário). +- `"name"`: O nome da matéria. +- `"code"`: O código da matéria na universidade. +- `"times"`: Uma lista de horários em que a matéria é ministrada. - `"professors"`: Uma lista de nomes de professores preferidos escolhidos pelo usuário. -- `"mode"`: O modo de montagem da grade de matérias, que pode ser manual ou automático. -- `"schedule"`: Uma lista de objetos representando a grade de matérias por dia. Cada objeto possui um campo `"day"` e uma lista de cursos `"courses"` para esse dia. -- `"courses"`: Uma lista de objetos representando as matérias selecionadas manualmente. Cada objeto contém o `"name"` (nome da matéria) e `"time"` (horário). - ### Update de Grade @@ -180,13 +258,13 @@ Esta rota permite ao usuário atualizar uma grade de matérias salva anteriormen **Requests:** -```json +```js headers = { "Authorization": "Token" } ``` **Response:** -```json +```js body: { "schedule_id": 123, "mode": "manual", @@ -194,6 +272,7 @@ body: { "courses": [ { "name": "Tópicos Especiais em Engenharia de Software", + "code": "ESW101", "times": [ ["23M34","Segunda e Terça - 10:00 a 12:00"], ["2T23","Segunda - 14:00 a 16:00"] @@ -202,6 +281,7 @@ body: { }, { "name": "Fisica 1", + "code": "FIS101", "times": [ ["45M34","Quarta e Quinta - 10:00 a 12:00"], ["6T23","Sexta - 14:00 a 16:00"] @@ -213,14 +293,13 @@ body: { } ``` - `"schedule_id"`: O identificador único da grade de matérias a ser atualizada. -- `"courses"`: Uma lista de objetos representando as matérias selecionadas manualmente. Cada objeto contém o `"name"` (nome da matéria), `"day"` (dia da semana) e `"time"` (horário). -- `"professors"`: Uma lista de nomes de professores preferidos escolhidos pelo usuário. +- `"courses"`: Uma lista de objetos representando as matérias selecionadas manualmente. Cada objeto contém o `"name"` (nome da matéria), `"code"` (código da disciplina), `"day"` (dia da semana) e `"time"` (horário). **Response:** A resposta confirmará a atualização bem-sucedida da grade de matérias. -```json +```js { "message": "Grade atualizada com sucesso." } @@ -235,7 +314,7 @@ Esta rota permite ao usuário pesquisar e encontrar informações detalhadas sob **Request:** -```json +```js query = "Cálculo 1" ``` @@ -245,7 +324,7 @@ query = "Cálculo 1" A resposta incluirá informações detalhadas sobre a matéria procurada. -```json +```js { "course_name": "Cálculo 1", "course_code": "MAT101", @@ -282,7 +361,7 @@ O usuário pode usar esta rota para excluir uma grade de matérias salva anterio **Requests:** -```json +```js headers = { "Authorization": "Token" } @@ -290,7 +369,7 @@ headers = { **Response:** -```json +```js { "schedule_id": 123 } From 8861cc8f2617cd6d726e714bca23f679662bfa72 Mon Sep 17 00:00:00 2001 From: Caio Date: Wed, 18 Oct 2023 22:25:21 -0300 Subject: [PATCH 4/6] docs(api): atualiza as rotas da API Co-authored-by: Mateus Vieira Co-authored-by: Gabriel Castelo --- docs/api.md | 520 +++++++++++++++++++++++++++------------------------- 1 file changed, 274 insertions(+), 246 deletions(-) diff --git a/docs/api.md b/docs/api.md index 253381a0..3157bc84 100644 --- a/docs/api.md +++ b/docs/api.md @@ -1,378 +1,406 @@ +--- +hide: + - navigation +--- + # Definição de rotas -## Rotas do web site "Sua Grade UnB" +Lorem ipsum dolor sit amet, consectetur adipiscing elit. Donec auctor, nisl eget ultricies ultricies, nunc nisl ultricies nunc, quis ul + +## Autenticação do Google + +**Método HTTP:** `POST`
+**Rota:** `/users/register` + +Esta rota permite ao usuário fazer o login usando o Google OAuth2. Caso o usuário não tenha uma conta, uma nova será criada. -### Autenticação do Google +**Request:** -**Método HTTP:** `GET` -**Rota:** `/auth/google` +O request deve conter um token de autenticação do Google. -Essa rota permite ao usuário fazer login com sua conta do Google. +```js +body = { + "access_token": "token" +} +``` +- `"access_token"`: O token de acesso do Google OAuth2. **Response:** A resposta conterá informações de autenticação bem-sucedida, incluindo um token de autenticação. +**Success (200 OK)** + ```js -{ - "routes": [ - { - "path": "/auth/google", - "method": "GET", - "description": "Iniciar autenticação do Google OAuth2.", - "scope": ["profile", "email"] - }, - { - "path": "/auth/google/callback", - "method": "GET", - "description": "Rota de retorno de chamada após a autenticação do Google OAuth2. Recebe o token de acesso do Google.", - "successRedirect": "/profile", - "failureRedirect": "/login", - "receivesAccessToken": true - }, - ], +headers = { + "Content-Type": "application/json", + "Set-Cookie": "refresh=; Secure; HttpOnly; SameSite=Lax; Expires=" +}, +body = { + "access": "token", + "first_name": "name", + "last_name": "name", + "email": "email" } +``` + +**Error (400 BAD REQUEST)** +```js +body = { + "errors": "descriptive error message" +} ``` -- `"access_token"`: O token de acesso que permite ao usuário autenticado acessar recursos protegidos. +## Login -### Consulta da Grade de Matérias +**Método HTTP:** `POST`
+**Rota:** `/users/login` -**Método HTTP:** `GET` -**Rota:** `/schedules` +Esta rota atualiza o *refresh-token* do usuário e retorna um novo *access-token*. -Esta rota permite ao usuário visualizar várias grades de matérias criadas. +**Request:** -**Requests:** +O request deve conter um *refresh-token*. ```js headers = { - "Authorization": "Token" + "Cookie": "refresh=" } ``` **Response:** +**Success (200 OK)** + ```js -{ - "schedule 1": { - "id": 123, - "name": "Grade 1", - "date": "2021-01-01", - "schedule": [ - { - "day": "Segunda-feira", - "courses": [ - { - "name": "Cálculo 1", - "time": "2M34" - "code": "MAT101" - "teacher": ["LUIZA YOKO"] - "classroom": "S1" - }, - { - "name": "Fisica 1", - "time": "2T23" - "code": "FIS101" - "teacher": ["RAFAEL MORGADO DA SILVA"] - "classroom": "S2" - } - ] - }, - { - "day": "Terça-feira", - "courses": [ - { - "name": "Cálculo 1", - "time": "3M34" - "code": "MAT101" - "teacher": ["LUIZA YOKO"] - "classroom": "S1" - }, - { - "name": "Fisica 1", - "time": "3T23" - "code": "FIS101" - "teacher": ["RAFAEL MORGADO DA SILVA"] - "classroom": "S2" - } - ] - } - ] - } - "schedule 2": { - "id": 456, - "name": "Grade 2", - "date": "2021-01-01", - "schedule": [ - { - "day": "Quarta-feira", - "courses": [ - { - "name": "Cálculo 1", - "time": "2M34" - "code": "MAT102" - "teacher": ["Ricardo Fragelli"] - "classroom": "S1" - }, - { - "name": "Fisica 1", - "time": "2T23" - "code": "FIS104" - "teacher": ["RAFAEL MORGADO DA SILVA"] - "classroom": "S2" - } - ] - }, - { - "day": "Sexta-feira", - "courses": [ - { - "name": "Cálculo 1", - "time": "3M34" - "code": "MAT102" - "teacher": ["Ricardo Fragelli"] - "classroom": "S1" - }, - { - "name": "Fisica 1", - "time": "3T23" - "code": "FIS104" - "teacher": ["RAFAEL MORGADO DA SILVA"] - "classroom": "S2" - } - ] - } - ] - } +headers = { + "Set-Cookie": "refresh=; Secure; HttpOnly; SameSite=Lax; Expires=" +}, +body = { + "access": "token", + "first_name": "name", + "last_name": "name", + "email": "email" } ``` -- `"schedule"`: Uma lista de objetos representando a grade de matérias por dia. Cada objeto possui um campo `"day"` e uma lista de cursos `"courses"` para esse dia. -- `"courses"`: Uma lista de objetos representando as matérias selecionadas manualmente. Cada objeto contém o `"name"` (nome da matéria), `"time"` (horário) e `"teacher"` (professor) e `"classroom"` (sala de aula). -- `"date"`: A data em que a grade de matérias foi criada. -- `"name"`: O nome da grade da matéria. -- `"id"`: O identificador único da grade de matérias. -- `"day"`: O dia da semana em que é ministrada a aula. -- `"time"`: Código que fornece o horário em que é ministrada a aula e bem o dia da semana em que acontece. -- `"teacher"`: O nome do professor que ministra a aula. -- `"classroom"`: O código da sala de aula em que é ministrada a aula. - - -### Visualização de Perfil +## Logout -**Método HTTP:** `GET` -**Rota:** `/profile` +**Método HTTP:** `POST`
+**Rota:** `users/logout` -Esta rota permite ao usuário visualizar seu perfil, incluindo informações pessoais e configurações. +Esta rota permite ao usuário fazer logout de sua conta no site. -**Requests:** +**Request:** ```js headers = { - "Authorization": "Token" + "Cookie": "refresh=", + "Authorization": "Bearer " } ``` **Response:** +**Suceess (200 OK)** + ```js -{ - "info": { - "photo": "link", - "name": "Client name", - "email": "client@email.com" - } +body = { + "message": "Successfully logged out." } ``` -- `"photo"`: A foto de perfil do usuário. -- `"name"`: O nome do usuário. -- `"email"`: O email do usuário. - -### Logout -**Método HTTP:** `GET` -**Rota:** `/logout` +**Error (400 BAD REQUEST)** -Esta rota permite ao usuário fazer logout de sua conta no site. +```js +body = { + "errors": "descriptive error message" +} +``` -**Requests:** +**Error (401 UNAUTHORIZED)** ```js -headers = { - "Authorization": "Token" +body = { + "errors": "access token not provided or invalid" } ``` -### Montagem de Grade +## Busca por Matéria -**Método HTTP:** `POST` -**Rota:** `/schedules/create` +**Método HTTP:** `GET`
+**Rota:** `/courses/?search=` -Esta rota permite ao usuário criar uma grade de matérias, selecionando manualmente as matérias e horários ou deixando o sistema escolher automaticamente por preferencias determinadas pelo usuário. +Esta rota permite ao usuário pesquisar e encontrar informações detalhadas sobre matérias potenciais que podem se relacionar com o termo de busca *(máximo 5)*. A busca deve ser pelo nome da matéria. **Response:** +A resposta incluirá informações detalhadas sobre as matérias potenciais que se relacionam com o termo de busca. + +**Success (200 OK):** + +```js +body = { + "courses": [ + { + "name": "Tópicos Especiais em Programação", + "code": "FGA0053", + "options": [ + { + "teachers": ["Edson Alves da Costa Junior"], + "schedule": "2M34", + "days": ["Segunda e Terça - 10:00 a 12:00"], + "classroom": "FGA - S1", + "workload": 60, + "class": 1 + } + ] + } + ] +} +``` + +**Error (400 BAD REQUEST):** + ```js -{ - "mode": "manual | automatic", - "preference": "M", +body = { + "errors": "descriptive error message" +} +``` + +## Montagem de Grade +**Método HTTP:** `POST`
+**Rota:** `/schedules/automatic/create` + +Esta rota permite ao usuário criar uma grade de matérias, selecionando manualmente as matérias e horários ou deixando o sistema escolher automaticamente por preferencias determinadas pelo usuário. Ao utilizar esta rota, o usuário receberá três opções de grade. + +**Request:** + +```js +body = { + "preference": "M|T|N", "courses": [ { "name": "Tópicos Especiais em Engenharia de Software", "code": "ESW101", - "times": [ - ["23M34","Segunda e Terça - 10:00 a 12:00"], - ["2T23","Segunda - 14:00 a 16:00"] - ], - "professors": ["BRUNO CESAR RIBAS", "EDSON ALVES DA COSTA JUNIOR"] + "options": [ + { + "teachers": ["Edson Alves da Costa Junior"], + "schedule": "2M34" + }, + { + "teachers": ["BRUNO CESAR RIBAS"], + "schedule": "2T23" + } + ] }, { "name": "Fisica 1", - "code": "FIS101", - "times": [ - ["45M34","Quarta e Quinta - 10:00 a 12:00"], - ["6T23","Sexta - 14:00 a 16:00"] - ], - "professors": ["LUIZA YOKO", "RAFAEL MORGADO DA SILVA"] - + "code": "FIS101" } ] } ``` -- `"mode"`: O modo de montagem da grade de matérias, que pode ser manual ou automático. -- `"preference"`: A preferência de horário escolhida pelo usuário (por exemplo, "M" para manhã, "T" para tarde, "N" para noite). -- `"courses"`: Uma lista de objetos representando as matérias selecionadas manualmente. Cada objeto contém o `"name"` (nome da matéria), `"code"` (código da disciplina), `"day"` (dia da semana) e `"time"` (horário). -- `"name"`: O nome da matéria. -- `"code"`: O código da matéria na universidade. -- `"times"`: Uma lista de horários em que a matéria é ministrada. -- `"professors"`: Uma lista de nomes de professores preferidos escolhidos pelo usuário. -### Update de Grade +- Caso as opções de matéria possuam horários ou professores ou ambos, o sistema dará preferência para escolha dessas opções. Caso contrário, o sistema escolherá automaticamente. -**Método HTTP:** `PUT` Rota: `/schedules/update` +**Response:** -Esta rota permite ao usuário atualizar uma grade de matérias salva anteriormente, caso deseje alterar uma configuração específica. +**Success (200 OK):** -**Requests:** +A resposta incluirá três opções de grade de matérias, com base nas preferências do usuário. ```js -headers = { - "Authorization": "Token" +body = { + "schedules": [ + { + "courses": [ + { + "FGA0053": { + "teachers": ["Edson Alves da Costa Junior"], + "schedule": "2M34" + }, + "FGA0030": { + "teachers": ["BRUNO CESAR RIBAS"], + "schedule": "2T23" + } + } + ] + }, + ... + ] } ``` -**Response:** + +**Error (400 BAD REQUEST):** + ```js -body: { - "schedule_id": 123, - "mode": "manual", +body = { + "errors": "descriptive error message" +} +``` + +## Salvar Grade + +**Método HTTP:** `POST`
+**Rota:** `/schedules/save` +Esta rota permite ao usuário salvar uma grade de matérias, caso deseje utilizá-la novamente no futuro. + +**Request:** + +```js +header = { + "Authorization": "Bearer " +}, +body = { + "id": 123, "courses": [ { - "name": "Tópicos Especiais em Engenharia de Software", - "code": "ESW101", - "times": [ - ["23M34","Segunda e Terça - 10:00 a 12:00"], - ["2T23","Segunda - 14:00 a 16:00"] - ], - "professors": ["BRUNO CESAR RIBAS", "EDSON ALVES DA COSTA JUNIOR"] - }, - { - "name": "Fisica 1", - "code": "FIS101", - "times": [ - ["45M34","Quarta e Quinta - 10:00 a 12:00"], - ["6T23","Sexta - 14:00 a 16:00"] - ], - "professors": ["LUIZA YOKO", "RAFAEL MORGADO DA SILVA"] - + "FGA0053": { + "teachers": ["Edson Alves da Costa Junior"], + "schedule": "2M34" + }, + "FGA0030": { + "teachers": ["BRUNO CESAR RIBAS"], + "schedule": "2T23" + } } ] } ``` -- `"schedule_id"`: O identificador único da grade de matérias a ser atualizada. -- `"courses"`: Uma lista de objetos representando as matérias selecionadas manualmente. Cada objeto contém o `"name"` (nome da matéria), `"code"` (código da disciplina), `"day"` (dia da semana) e `"time"` (horário). **Response:** -A resposta confirmará a atualização bem-sucedida da grade de matérias. +**Success (201 CREATED):** + +A resposta confirmará a criação bem-sucedida da grade de matérias. ```js -{ - "message": "Grade atualizada com sucesso." +body = { + "message": "Grade salva com sucesso." } ``` -## Busca por Matéria +**Error (400 BAD REQUEST):** -**Método HTTP:** `GET` -**Rota:** `/courses/search` +```js +body = { + "errors": "descriptive error message" +} +``` -Esta rota permite ao usuário pesquisar e encontrar informações detalhadas sobre uma matéria específica na universidade. +**Error (401 UNAUTHORIZED):** + +```js +body = { + "errors": "access token not provided or invalid" +} +``` + +## Consulta da Grade de Matérias + +**Método HTTP:** `GET`
+**Rota:** `/schedules` + +Esta rota permite ao usuário visualizar as grades de matérias criadas e salvas por ele. **Request:** ```js -query = "Cálculo 1" +headers = { + "Authorization": "Bearer " +} ``` -- `query`: A consulta que o usuário deseja fazer para encontrar informações sobre uma matéria específica. - **Response:** -A resposta incluirá informações detalhadas sobre a matéria procurada. +**Success (200 OK):** + +A resposta incluirá uma lista de grades de matérias salvas pelo usuário. ```js -{ - "course_name": "Cálculo 1", - "course_code": "MAT101", - "description": "Este curso aborda os conceitos fundamentais de cálculo, incluindo limites, derivadas e integrais.", - "professors": ["LUIZA YOKO", "RICARDO FRAGELLI"], - "schedule": [ - { - "day": "Segunda-feira", - "time": "2M34" - }, +body = { + "schedules": [ { - "day": "Terça-feira", - "time": "2T23" + "id": 123, + "courses": [ + { + "FGA0053": { + "teachers": ["Edson Alves da Costa Junior"], + "schedule": "2M34" + }, + "FGA0030": { + "teachers": ["BRUNO CESAR RIBAS"], + "schedule": "2T23" + } + } + ] } ] } ``` -- `"course_name"`: O nome da matéria pesquisada. +**Error (400 BAD REQUEST):** -- `"course_code"`: O código da matéria na universidade. +```js +body = { + "errors": "descriptive error message" +} +``` -- `"description"`: Uma breve descrição do conteúdo do curso. +**Error (401 UNAUTHORIZED):** -- `"professors"`: Uma lista de professores que ministram o curso. +```js +body = { + "errors": "access token not provided or invalid" +} +``` -- `"schedule"`: Um horário típico de aulas para a matéria, incluindo os dias da semana e horários. -### Deleção de Grade Salva +## Deleção de Grade Salva -**Método HTTP:** `DELETE` -**Rota:** `/schedules` +**Método HTTP:** `DELETE`
+**Rota:** `/schedules/delete` -O usuário pode usar esta rota para excluir uma grade de matérias salva anteriormente, caso deseje remover uma configuração específica. +Esta rota permite ao usuário excluir uma grade de matérias salva anteriormente. -**Requests:** +**Request:** ```js headers = { - "Authorization": "Token" + "Authorization": "Bearer " +}, +body = { + "id": 123 } ``` **Response:** +**Success (200 OK):** + +A resposta confirmará a exclusão bem-sucedida da grade de matérias. + ```js -{ - "schedule_id": 123 +body = { + "message": "Successfully deleted." } ``` -- `"schedule_id"`: O identificador único da grade de matérias a ser excluída. +**Error (400 BAD REQUEST):** + +```js +body = { + "errors": "descriptive error message" +} +``` + +**Error (401 UNAUTHORIZED):** + +```js +body = { + "errors": "access token not provided or invalid" +} +``` \ No newline at end of file From ce1a7d0a84b4cabf818074b0ded288b44885f743 Mon Sep 17 00:00:00 2001 From: Caio Date: Wed, 18 Oct 2023 22:40:27 -0300 Subject: [PATCH 5/6] =?UTF-8?q?docs(api):=20adiciona=20a=20descri=C3=A7?= =?UTF-8?q?=C3=A3o=20para=20definir=20rotas?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Mateus Vieira Co-authored-by: Gabriel Castelo --- docs/api.md | 54 ++++++++++++++++++++++++++--------------------------- 1 file changed, 27 insertions(+), 27 deletions(-) diff --git a/docs/api.md b/docs/api.md index 3157bc84..2372bf61 100644 --- a/docs/api.md +++ b/docs/api.md @@ -5,7 +5,7 @@ hide: # Definição de rotas -Lorem ipsum dolor sit amet, consectetur adipiscing elit. Donec auctor, nisl eget ultricies ultricies, nunc nisl ultricies nunc, quis ul +Nesta seção, serão definidas as rotas da API, bem como os métodos HTTP e os parâmetros necessários para cada uma delas. ## Autenticação do Google @@ -18,7 +18,7 @@ Esta rota permite ao usuário fazer o login usando o Google OAuth2. Caso o usuá O request deve conter um token de autenticação do Google. -```js +```js linenums="1" body = { "access_token": "token" } @@ -31,7 +31,7 @@ A resposta conterá informações de autenticação bem-sucedida, incluindo um t **Success (200 OK)** -```js +```js linenums="1" headers = { "Content-Type": "application/json", "Set-Cookie": "refresh=; Secure; HttpOnly; SameSite=Lax; Expires=" @@ -46,7 +46,7 @@ body = { **Error (400 BAD REQUEST)** -```js +```js linenums="1" body = { "errors": "descriptive error message" } @@ -63,7 +63,7 @@ Esta rota atualiza o *refresh-token* do usuário e retorna um novo *access-token O request deve conter um *refresh-token*. -```js +```js linenums="1" headers = { "Cookie": "refresh=" } @@ -73,7 +73,7 @@ headers = { **Success (200 OK)** -```js +```js linenums="1" headers = { "Set-Cookie": "refresh=; Secure; HttpOnly; SameSite=Lax; Expires=" }, @@ -94,7 +94,7 @@ Esta rota permite ao usuário fazer logout de sua conta no site. **Request:** -```js +```js linenums="1" headers = { "Cookie": "refresh=", "Authorization": "Bearer " @@ -105,7 +105,7 @@ headers = { **Suceess (200 OK)** -```js +```js linenums="1" body = { "message": "Successfully logged out." } @@ -113,7 +113,7 @@ body = { **Error (400 BAD REQUEST)** -```js +```js linenums="1" body = { "errors": "descriptive error message" } @@ -121,7 +121,7 @@ body = { **Error (401 UNAUTHORIZED)** -```js +```js linenums="1" body = { "errors": "access token not provided or invalid" } @@ -140,7 +140,7 @@ A resposta incluirá informações detalhadas sobre as matérias potenciais que **Success (200 OK):** -```js +```js linenums="1" body = { "courses": [ { @@ -163,7 +163,7 @@ body = { **Error (400 BAD REQUEST):** -```js +```js linenums="1" body = { "errors": "descriptive error message" } @@ -178,7 +178,7 @@ Esta rota permite ao usuário criar uma grade de matérias, selecionando manualm **Request:** -```js +```js linenums="1" body = { "preference": "M|T|N", "courses": [ @@ -212,7 +212,7 @@ body = { A resposta incluirá três opções de grade de matérias, com base nas preferências do usuário. -```js +```js linenums="1" body = { "schedules": [ { @@ -236,7 +236,7 @@ body = { **Error (400 BAD REQUEST):** -```js +```js linenums="1" body = { "errors": "descriptive error message" } @@ -251,7 +251,7 @@ Esta rota permite ao usuário salvar uma grade de matérias, caso deseje utiliz **Request:** -```js +```js linenums="1" header = { "Authorization": "Bearer " }, @@ -278,7 +278,7 @@ body = { A resposta confirmará a criação bem-sucedida da grade de matérias. -```js +```js linenums="1" body = { "message": "Grade salva com sucesso." } @@ -286,7 +286,7 @@ body = { **Error (400 BAD REQUEST):** -```js +```js linenums="1" body = { "errors": "descriptive error message" } @@ -294,7 +294,7 @@ body = { **Error (401 UNAUTHORIZED):** -```js +```js linenums="1" body = { "errors": "access token not provided or invalid" } @@ -309,7 +309,7 @@ Esta rota permite ao usuário visualizar as grades de matérias criadas e salvas **Request:** -```js +```js linenums="1" headers = { "Authorization": "Bearer " } @@ -321,7 +321,7 @@ headers = { A resposta incluirá uma lista de grades de matérias salvas pelo usuário. -```js +```js linenums="1" body = { "schedules": [ { @@ -345,7 +345,7 @@ body = { **Error (400 BAD REQUEST):** -```js +```js linenums="1" body = { "errors": "descriptive error message" } @@ -353,7 +353,7 @@ body = { **Error (401 UNAUTHORIZED):** -```js +```js linenums="1" body = { "errors": "access token not provided or invalid" } @@ -368,7 +368,7 @@ Esta rota permite ao usuário excluir uma grade de matérias salva anteriormente **Request:** -```js +```js linenums="1" headers = { "Authorization": "Bearer " }, @@ -383,7 +383,7 @@ body = { A resposta confirmará a exclusão bem-sucedida da grade de matérias. -```js +```js linenums="1" body = { "message": "Successfully deleted." } @@ -391,7 +391,7 @@ body = { **Error (400 BAD REQUEST):** -```js +```js linenums="1" body = { "errors": "descriptive error message" } @@ -399,7 +399,7 @@ body = { **Error (401 UNAUTHORIZED):** -```js +```js linenums="1" body = { "errors": "access token not provided or invalid" } From 498e9513e58e4a68660c0292614437069d76cd8a Mon Sep 17 00:00:00 2001 From: Caio Date: Wed, 18 Oct 2023 22:41:22 -0300 Subject: [PATCH 6/6] =?UTF-8?q?docs(mkdocs):=20adiciona=20se=C3=A7=C3=A3o?= =?UTF-8?q?=20"api"?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Mateus Vieira Co-authored-by: Gabriel Castelo --- mkdocs.yml | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/mkdocs.yml b/mkdocs.yml index d49a51ff..4f50cdf5 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -8,15 +8,26 @@ nav: - Sprint 0: sprints/sprint-0.md - Sprint 1: sprints/sprint-1.md - Sprint 2: sprints/sprint-2.md + - API: api.md theme: name: material features: - navigation.tabs - navigation.tabs.sticky + - content.code.copy palette: primary: "indigo" icon: repo: fontawesome/brands/github + +markdown_extensions: + - pymdownx.highlight: + anchor_linenums: true + line_spans: __span + pygments_lang_class: true + - pymdownx.inlinehilite + - pymdownx.snippets + - pymdownx.superfences \ No newline at end of file