ikaro-souza/NETCoreAPIBoilerplate

:book: Estudo API com .NET Core

NET Core API Boilerplate

📖 O projeto de estudo API com .NET Core servirá como um modelo padrão em prpjetos futuros

Configuração de máquina

Para executar esse projeto na sua máquina, é necessário ter instalado nela o .Net 5.0 SDK e o PostgreSQL. OBS: Se o Visual Studio estiver instalado na sua máquina, é recomendado atualiza-lo ou desinstala-lo antes da instalação do SDK.

Sumário

• Configuração de máquina
• Configuração do VS Code
• Documentando a Api

Configuração do VS Code

Extensões

• ASP.NET Core Snippets
• Bracket Pair Colorizer
• C#
• C# Extensions
• C# XML Documentation
• GitLens (Eric Amudio)
• Path Intellisense
• PostgresSQL (Chris Kolkman)
• Visual Studio Intellicode
• Conventional Commits
• C# FixFormat - Fix format of usings /indents/braces/empty lines
• MSBuild Project Tools
• VSCode Solution Explorer
• .NET Core Test Explorer

Rodando o projeto

Há dois modos de rodar o projeto:

• .Net CLI: Para rodar pelo CLI, basta abrir o terminal no VS Code e executar o comando dotnet watch run.
  • Vantagem: Possui a feature de hot reload (quando o watch é utilizado).
• Debugger do VS Code: basta pressionar F5.
  • Vantagem: Permite o debug.

Documentando a Api

A documentação da Api é auto-gerada pelo Swagger, para complementar essa documentação, são usados os recursos de Atributos e Comentários XML. O dev que irá contribuir com este projeto precisa, de regra geral, sempre usar os comentários, contendo obrigatoriamente a tag <summary> e usar também as devidas anotações.

Sumário

• Documentação de Controllers e Actions

Referências

• Roteamento de atributos: https://docs.microsoft.com/en-us/aspnet/core/mvc/controllers/routing?view=aspnetcore-5.0#ar

• Comentário XML: https://docs.microsoft.com/en-us/dotnet/csharp/codedoc

• Controllers: https://docs.microsoft.com/en-us/aspnet/mvc/overview/older-versions-1/controllers-and-routing/aspnet-mvc-controllers-overview-cs#understanding-controllers

• Actions: https://docs.microsoft.com/en-us/aspnet/mvc/overview/older-versions-1/controllers-and-routing/aspnet-mvc-controllers-overview-cs#understanding-controller-actions

• Model Binding: https://docs.microsoft.com/en-us/aspnet/core/mvc/models/model-binding?view=aspnetcore-5.0#sources

• Rotas com métodos Http: https://docs.microsoft.com/en-us/aspnet/core/mvc/controllers/routing?view=aspnetcore-5.0#http-verb-templates

• Tipos de retorno de ação de controlador: https://docs.microsoft.com/en-us/aspnet/core/web-api/action-return-types?view=aspnetcore-5.0

Documentação de Controllers e Actions

Nos comentários XML, use ao menos as tags <returns> e <response>:

/// <summary>
/// Essa ação faz algo e retorna uma coisa.
/// </summary>
/// <returns>Alguma coisa</returns>
/// <response code="200">Retonar alguma coisa</response>
/// <response code="404">Alguma coisa não foi encontrada</response>
[HttpGet]
public IActionResult Action() {}

Coloque os atributos [Http-MétodoHttp] e [PoducesResponseType] em cada ação dos controladores:

/// <summary> ...
[HttpPost]
[ProducesResponseType(StatusCodes.Status200OK)]
[ProducesResponseType(StatusCodes.Status404NotFound)]
public IActionResult Action() {}

Se a requisição tem corpo, coloque o atributo [FromBody] no parâmetro da ação:

/// <summary> ...
// Anotações ...
public IActionResult Action([FromBody] Type requestBody) {}

Se a requisição recebe algum valor da url, como um Id, por exemplo, use a anotação [FromRoute] no parâmetro da ação e defina esse parâmetro na rota da ação:

/// <summary> ...
[HttpDelete("{Id?}")]
public IActionResult Action([FromRoute] long? Id) {}

Fazer o processo de subir o repo ...

Análise de tecnologias e documentações (melhores práticas; pros e cons)

• Como contribuir
  • Fork
  • PR
  • Issues
  • Padrão de commit (Conventional commit)
  • Estilização de código
  • Gitlab / Taiga.io