dotnet-api-boilerplate

Introduction to DotNet API Boilerplate

The DotNet API Boilerplate is a comprehensive template project designed specifically for creating a Web API using .Net 8.0. It serves as a solid foundation that incorporates essential technologies and design patterns commonly used in restful APIs, streamlining the development process and making it easier to kickstart your projects.

Key Features

1. Integrated Technologies: The boilerplate includes a range of integrated technologies such as MediatR for handling request and response messages, Swagger for API documentation, Mapster for object mapping instead of AutoMapper, and Serilog for logging.

2. Project Accessibility: With support for both stand-alone execution and containerization with Docker, the boilerplate offers flexibility in how developers can operate their projects locally or in production environments.

3. Comprehensive Project Structure: The project is organized into four main parts — Services, Application, Domain, and Infrastructure, each with specific responsibilities from handling user data to executing core business logic.

4. Authentication and Authorization: The boilerplate comes with built-in support for user authentication. It features endpoints for user registration and login, ensuring that security can be easily managed from the start.

5. Extensive Testing Capabilities: Test coverage is a priority in this project, with unit and integration tests readily available. The integration tests even utilize Docker to manage a Postgres container for realistic test scenarios.

6. Developer-Friendly Additions: The boilerplate simplifies the developer experience with features like strongly typed IDs, response pagination, and OpenTelemetry support for monitoring.

Project Setup and Usage

Running Locally

To get started, clone the project repository and ensure you have the latest .Net SDK and a compatible IDE like Visual Studio, Visual Studio Code, or Rider.

• Standalone Setup:

  1. Ensure Postgres is running. Docker can be used to start the database server effortlessly with the command docker-compose up -d db-server.
  2. Navigate to the src/Boilerplate.Api folder and start the API using dotnet run, or by configuring it as the startup project in your IDE.
  3. Access the application's Swagger UI at http://localhost:7122/api-docs.

• Docker Setup:

  1. At the root directory, execute docker-compose up -d to start both the application and the database.
  2. For HTTPS support, generate a certificate using dotnet dev-certs https -ep https/aspnetapp.pfx -p yourpassword.
  3. Again, Swagger UI can be accessed to view API documentation.

Running Tests

Ensure Docker is operational as the integration tests spin up a Postgres container. Use dotnet test in the root folder to run tests, or use the Test Explorer in Visual Studio for a graphical overview.

Project Structure

1. Services: Hosts the API and related projects that deliver data to users.
2. Application: Handles data transformations and business logic between the API and domain layers.
3. Domain: Contains business models, enumerations, and common interfaces.
4. Infra: Manages database contexts and configurations for external data access.

Modifying for Personal Use

The boilerplate is highly customizable. Developers are advised to adjust folder names, project namespaces, and Docker configurations to fit their individual project requirements.

Migration Setup

To perform migrations, install the dotnet-ef tool globally. Depending on your operating system, use the command syntax provided in the project documentation to add migrations.

Community and Support

If you find this project helpful, consider starring it on GitHub to show your support. This project is influenced by similar initiatives like the Netcore Boilerplate and Equinox Project, sharing knowledge and techniques across the developer community.

Under the MIT license, this project is openly accessible for modification and distribution, encouraging further development and usage.

Whether you are a seasoned developer or new to API development in .Net, the DotNet API Boilerplate provides a robust starting point, minimizing initial setup and allowing you to focus on building feature-rich applications.