Merge pull request #6 from Mucaccino/docfx

Documentation pages with docfx updates

.github/workflows/pages.yml

@@ -33,8 +33,9 @@ jobs:
       with:
         dotnet-version: 8.x
 
+    - run: dotnet tool update -g NSwag.ConsoleCore
     - run: dotnet tool update -g docfx
-    - run: docfx ./docfx.json
+    - run: make docs
 
     - name: Upload artifact
       uses: actions/upload-pages-artifact@v3

.gitignore

@@ -38,3 +38,6 @@ obj/
 TestResults/
 /_site/
 /api/
+/apipage
+/restapi/*
+!restapi/toc.yml

Motto.WebApi/Motto.WebApi.csproj

@@ -1,4 +1,4 @@
-<Project Sdk="Microsoft.NET.Sdk.Web">
+<Project Sdk="Microsoft.NET.Sdk.Web">
   <PropertyGroup>
     <TargetFramework>net8.0</TargetFramework>
     <Nullable>enable</Nullable>

Motto.WebApi/Program.cs

@@ -16,10 +16,13 @@
 
 namespace Motto.WebApi;
 
+/// <summary>
+/// The Program class is the entry point of the application.
+/// </summary>
 public partial class Program {
 
     private static void Main(string[] args)
-    {
+    {        
         var builder = WebApplication.CreateBuilder(args);
 
         // Configure logging

docfx.json

@@ -9,14 +9,33 @@
           ]
         }
       ],
+      "namespaceLayout": "flattened",
+      "enumSortOrder": "declaringOrder",
+      "outputFormat": "mref",
       "dest": "api"
+    },
+    {
+      "src": [
+        {
+          "files": [
+            "**/*.csproj"
+          ],
+          "src": "./"
+        }
+      ],
+      "namespaceLayout": "nested",
+      "enumSortOrder": "declaringOrder",
+      "outputFormat": "apiPage",
+      "dest": "apipage"
     }
   ],
   "build": {
     "content": [
       {
         "files": [
-          "**/*.{md,yml}"
+          "**/*.{md,yml}",
+          "restapi/**",
+          "apipage/**"          
         ],
         "exclude": [
           "_site/**"
@@ -26,11 +45,13 @@
     "resource": [
       {
         "files": [
-          "images/**"
+          "images/**",
+          "makefile",
+          "restapi/clients.ts"
         ]
       }
     ],
-    "output": "_site",
+    "dest": "_site",
     "template": [
       "default",
       "modern"
@@ -42,6 +63,7 @@
       "pdf": false
     },
     "keepFileLink": false,
-    "postProcessors": ["ExtractSearchIndex"]
+    "exportViewModel": true,
+    "postProcessors": []
   }
 }

docs/project.md

@@ -1,5 +1,64 @@
 # O Projeto
 
-O `Motto.WebApi` é uma **webapi** do dotnet e possui implementação manual do JWT para autenticação e o Swagger UI configurado no ambiente de desenvolvimento, bem como o ReDocs.
+O `Motto.WebApi` é uma **webapi** do dotnet e possui implementação manual do JWT para autenticação e o Swagger UI configurado no ambiente de desenvolvimento.
 
-O aplicativo possui dois tipos de usuários - admin (`Admin`) e entregador (`DeliveryDriver`) - e cada end-point criado possui sua devida autorização.
+O aplicativo possui dois tipos de usuários - admin (`Admin`) e entregador (`DeliveryDriver`) - e cada end-point criado possui sua devida autorização.
+
+## Requisitos não funcionais 
+- A aplicação deverá ser construida com .Net utilizando C#.
+- Utilizar apenas os seguintes bancos de dados (Postgress, MongoDB)
+    - Não utilizar PL/pgSQL
+- Escolha o sistema de mensageria de sua preferencia( RabbitMq, Sqs/Sns , Kafka, Gooogle Pub/Sub ou qualquer outro)
+
+## Aplicação a ser desenvolvida
+Seu objetivo é criar uma aplicação para gerenciar aluguel de motos e entregadores. Quando um entregador estiver registrado e com uma locação ativa poderá também efetuar entregas de pedidos disponíveis na plataforma.
+
+### Casos de uso
+- Eu como usuário admin quero cadastrar uma nova moto.
+  - Os dados obrigatórios da moto são Identificador, Ano, Modelo e Placa
+  - A placa é um dado único e não pode se repetir.
+  - Quando a moto for cadastrada a aplicação deverá gerar um evento de moto cadastrada
+    - A notificação deverá ser publicada por mensageria.
+    - Criar um consumidor para notificar quando o ano da moto for "2024"
+    - Assim que a mensagem for recebida, deverá ser armazenada no banco de dados para consulta futura.
+- Eu como usuário admin quero consultar as motos existentes na plataforma e conseguir filtrar pela placa.
+- Eu como usuário admin quero modificar uma moto alterando apenas sua placa que foi cadastrado indevidamente
+- Eu como usuário admin quero remover uma moto que foi cadastrado incorretamente, desde que não tenha registro de locações.
+- Eu como usuário entregador quero me cadastrar na plataforma para alugar motos.
+    - Os dados do entregador são( identificador, nome, cnpj, data de nascimento, número da CNHh, tipo da CNH, imagemCNH)
+    - Os tipos de cnh válidos são A, B ou ambas A+B.
+    - O cnpj é único e não pode se repetir.
+    - O número da CNH é único e não pode se repetir.
+- Eu como entregador quero enviar a foto de minha cnh para atualizar meu cadastro.
+    - O formato do arquivo deve ser png ou bmp.
+    - A foto não poderá ser armazenada no banco de dados, você pode utilizar um serviço de storage( disco local, amazon s3, minIO ou outros).
+- Eu como entregador quero alugar uma moto por um período.
+    - Os planos disponíveis para locação são:
+        - 7 dias com um custo de R$30,00 por dia
+        - 15 dias com um custo de R$28,00 por dia
+        - 30 dias com um custo de R$22,00 por dia
+        - 45 dias com um custo de R$20,00 por dia
+        - 50 dias com um custo de R$18,00 por dia
+    - A locação obrigatóriamente tem que ter uma data de inicio e uma data de término e outra data de previsão de término.
+    - O inicio da locação obrigatóriamente é o primeiro dia após a data de criação.
+    - Somente entregadores habilitados na categoria A podem efetuar uma locação
+- Eu como entregador quero informar a data que irei devolver a moto e consultar o valor total da locação.
+    - Quando a data informada for inferior a data prevista do término, será cobrado o valor das diárias e uma multa adicional
+        - Para plano de 7 dias o valor da multa é de 20% sobre o valor das diárias não efetivadas.
+        - Para plano de 15 dias o valor da multa é de 40% sobre o valor das diárias não efetivadas.
+    - Quando a data informada for superior a data prevista do término, será cobrado um valor adicional de R$50,00 por diária adicional.
+
+
+## Diferenciais 🚀
+- Testes unitários
+- Testes de integração
+- EntityFramework e/ou Dapper
+- Docker e Docker Compose
+- Design Patterns
+- Documentação
+- Tratamento de erros
+- Arquitetura e modelagem de dados
+- Código escrito em língua inglesa
+- Código limpo e organizado
+- Logs bem estruturados
+- Seguir convenções utilizadas pela comunidade

docs/toc.yml

@@ -2,6 +2,7 @@
 - href: ../README.md
 - href: solution.md
 - href: project.md
+- href: ../restapi/swagger.json
 
 - name: Estrutura
 - href: docker.md

makefile

@@ -2,6 +2,7 @@
 DOCKER_COMPOSE = docker-compose
 DOTNET = dotnet
 DOCKFX = docfx
+NSWAG = nswag
 TESTS_PROJECT = Motto.Tests
 EF_PROJECT = Motto.Data
 Command := $(firstword $(MAKECMDGOALS))
@@ -10,19 +11,13 @@ Arguments := $(wordlist 2,$(words $(MAKECMDGOALS)),$(MAKECMDGOALS))
 # Targets
 .PHONY: all build setup services projects docs
 
-# Build, setup and up
-all: setup
-
 # Up services and setup database
 setup: services update
 
 # Update database
 update:
 	$(DOTNET) ef database update --project $(EF_PROJECT)
 
-# Up services and projects
-all: services projects
-
 # Up only services
 services:
 	$(DOCKER_COMPOSE) up -d --build
@@ -31,6 +26,9 @@ services:
 projects:
 	$(DOCKER_COMPOSE) -f docker-compose.yml -f docker-compose.projects.yml up -d --build
 
+# Up services and projects
+complete: services projects
+
 # Down containers
 down:
 	$(DOCKER_COMPOSE) -f docker-compose.yml -f docker-compose.projects.yml down
@@ -39,13 +37,27 @@ down:
 tests: services
 	$(DOTNET) test ./$(TESTS_PROJECT)/$(TESTS_PROJECT).csproj
 
-# Run docfx (with serve mode)
+# Run dotnet clean
+clean: 
+	$(DOTNET) clean
+
+# Run docfx
 docs:
+	$(NSWAG) aspnetcore2openapi /project:Motto.WebApi/Motto.WebApi.csproj /nobuild:false /output:restapi/swagger.json
+	$(NSWAG) openapi2tsclient /input:restapi/swagger.json /output:restapi/clients.ts
+	$(NSWAG) openapi2csclient /input:restapi/swagger.json /classname:MottoServiceClient /namespace:Motto /output:restapi/clients.cs
+# make docs serve
 ifeq (serve, $(filter serve,$(MAKECMDGOALS)))
 	$(DOCKFX) --serve
 else
 	$(DOCKFX) 
 endif
 
+# Install dependencies tools
+dependencies:
+	$(DOTNET) tool install -g dotnet-ef
+	$(DOTNET) tool install -g NSwag.ConsoleCore
+	$(DOTNET) tool install -g docfx
+
 %:
 	@:

restapi/toc.yml

@@ -0,0 +1,7 @@
+- name: REST Api
+  href: swagger.json
+- name: Clients
+- name: Download TS
+  href: clients.ts
+- name: Download C#
+  href: clients.cs

toc.yml

@@ -1,4 +1,8 @@
 - name: Documentation
   href: docs/
 - name: Reference
-  href: api/
+  href: api/
+- name: Api Page
+  href: apipage/
+- name: REST Api
+  href: restapi/