diff --git a/docs/api.md b/docs/api.md new file mode 100644 index 00000000..2372bf61 --- /dev/null +++ b/docs/api.md @@ -0,0 +1,406 @@ +--- +hide: + - navigation +--- + +# Definição de rotas + +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 + +**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. + +**Request:** + +O request deve conter um token de autenticação do Google. + +```js linenums="1" +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 linenums="1" +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 linenums="1" +body = { + "errors": "descriptive error message" +} +``` + +## Login + +**Método HTTP:** `POST`
+**Rota:** `/users/login` + +Esta rota atualiza o *refresh-token* do usuário e retorna um novo *access-token*. + +**Request:** + +O request deve conter um *refresh-token*. + +```js linenums="1" +headers = { + "Cookie": "refresh=" +} +``` + +**Response:** + +**Success (200 OK)** + +```js linenums="1" +headers = { + "Set-Cookie": "refresh=; Secure; HttpOnly; SameSite=Lax; Expires=" +}, +body = { + "access": "token", + "first_name": "name", + "last_name": "name", + "email": "email" +} +``` + +## Logout + +**Método HTTP:** `POST`
+**Rota:** `users/logout` + +Esta rota permite ao usuário fazer logout de sua conta no site. + +**Request:** + +```js linenums="1" +headers = { + "Cookie": "refresh=", + "Authorization": "Bearer " +} +``` + +**Response:** + +**Suceess (200 OK)** + +```js linenums="1" +body = { + "message": "Successfully logged out." +} +``` + +**Error (400 BAD REQUEST)** + +```js linenums="1" +body = { + "errors": "descriptive error message" +} +``` + +**Error (401 UNAUTHORIZED)** + +```js linenums="1" +body = { + "errors": "access token not provided or invalid" +} +``` + +## Busca por Matéria + +**Método HTTP:** `GET`
+**Rota:** `/courses/?search=` + +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 linenums="1" +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 linenums="1" +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 linenums="1" +body = { + "preference": "M|T|N", + "courses": [ + { + "name": "Tópicos Especiais em Engenharia de Software", + "code": "ESW101", + "options": [ + { + "teachers": ["Edson Alves da Costa Junior"], + "schedule": "2M34" + }, + { + "teachers": ["BRUNO CESAR RIBAS"], + "schedule": "2T23" + } + ] + }, + { + "name": "Fisica 1", + "code": "FIS101" + } + ] +} +``` + +- 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. + +**Response:** + +**Success (200 OK):** + +A resposta incluirá três opções de grade de matérias, com base nas preferências do usuário. + +```js linenums="1" +body = { + "schedules": [ + { + "courses": [ + { + "FGA0053": { + "teachers": ["Edson Alves da Costa Junior"], + "schedule": "2M34" + }, + "FGA0030": { + "teachers": ["BRUNO CESAR RIBAS"], + "schedule": "2T23" + } + } + ] + }, + ... + ] +} +``` + +**Error (400 BAD REQUEST):** + +```js linenums="1" +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 linenums="1" +header = { + "Authorization": "Bearer " +}, +body = { + "id": 123, + "courses": [ + { + "FGA0053": { + "teachers": ["Edson Alves da Costa Junior"], + "schedule": "2M34" + }, + "FGA0030": { + "teachers": ["BRUNO CESAR RIBAS"], + "schedule": "2T23" + } + } + ] +} +``` + +**Response:** + +**Success (201 CREATED):** + +A resposta confirmará a criação bem-sucedida da grade de matérias. + +```js linenums="1" +body = { + "message": "Grade salva com sucesso." +} +``` + +**Error (400 BAD REQUEST):** + +```js linenums="1" +body = { + "errors": "descriptive error message" +} +``` + +**Error (401 UNAUTHORIZED):** + +```js linenums="1" +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 linenums="1" +headers = { + "Authorization": "Bearer " +} +``` + +**Response:** + +**Success (200 OK):** + +A resposta incluirá uma lista de grades de matérias salvas pelo usuário. + +```js linenums="1" +body = { + "schedules": [ + { + "id": 123, + "courses": [ + { + "FGA0053": { + "teachers": ["Edson Alves da Costa Junior"], + "schedule": "2M34" + }, + "FGA0030": { + "teachers": ["BRUNO CESAR RIBAS"], + "schedule": "2T23" + } + } + ] + } + ] +} +``` + +**Error (400 BAD REQUEST):** + +```js linenums="1" +body = { + "errors": "descriptive error message" +} +``` + +**Error (401 UNAUTHORIZED):** + +```js linenums="1" +body = { + "errors": "access token not provided or invalid" +} +``` + +## Deleção de Grade Salva + +**Método HTTP:** `DELETE`
+**Rota:** `/schedules/delete` + +Esta rota permite ao usuário excluir uma grade de matérias salva anteriormente. + +**Request:** + +```js linenums="1" +headers = { + "Authorization": "Bearer " +}, +body = { + "id": 123 +} +``` + +**Response:** + +**Success (200 OK):** + +A resposta confirmará a exclusão bem-sucedida da grade de matérias. + +```js linenums="1" +body = { + "message": "Successfully deleted." +} +``` + +**Error (400 BAD REQUEST):** + +```js linenums="1" +body = { + "errors": "descriptive error message" +} +``` + +**Error (401 UNAUTHORIZED):** + +```js linenums="1" +body = { + "errors": "access token not provided or invalid" +} +``` \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml index faf5ce5c..77124400 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -9,15 +9,26 @@ nav: - Sprint 1: sprints/sprint-1.md - Sprint 2: sprints/sprint-2.md - Sprint 3: sprints/sprint-3.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