https://github.com/mreshboboyev/aspire-customization
ApiService is a modern .NET 9 Web API that integrates OpenAPI, Swagger UI, and ReDoc for interactive API documentation. It includes custom service defaults and Scalar integration for efficient data handling, ensuring scalability, flexibility, and ease of use.
https://github.com/mreshboboyev/aspire-customization
api-best-practices api-documentation asp-net-core c-sharp custom-service-defaults dotnet-core-9 open-api redoc rest-api scalable-systems scalar swagger web-api
Last synced: about 2 months ago
JSON representation
ApiService is a modern .NET 9 Web API that integrates OpenAPI, Swagger UI, and ReDoc for interactive API documentation. It includes custom service defaults and Scalar integration for efficient data handling, ensuring scalability, flexibility, and ease of use.
- Host: GitHub
- URL: https://github.com/mreshboboyev/aspire-customization
- Owner: MrEshboboyev
- Created: 2025-02-04T17:22:06.000Z (over 1 year ago)
- Default Branch: master
- Last Pushed: 2025-02-24T15:52:57.000Z (over 1 year ago)
- Last Synced: 2025-02-24T16:35:49.970Z (over 1 year ago)
- Topics: api-best-practices, api-documentation, asp-net-core, c-sharp, custom-service-defaults, dotnet-core-9, open-api, redoc, rest-api, scalable-systems, scalar, swagger, web-api
- Language: C#
- Homepage:
- Size: 10.7 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Aspire Customization - Enhanced Weather Forecast Service
This project demonstrates a production-ready implementation of a weather forecast service using .NET Aspire with real-world requirements and best practices.
## Features
- **Full CRUD Operations**: Complete REST API for weather forecasts
- **Health Checks**: Comprehensive health monitoring
- **API Documentation**: Swagger UI, ReDoc, and Scalar integration
- **Containerization**: Docker support for deployment
- **Observability**: OpenTelemetry integration
- **Resilience**: Built-in resilience patterns
- **Service Discovery**: Automatic service discovery
- **CORS Support**: Cross-origin resource sharing configuration
- **Response Compression**: Optimized payload delivery
- **Configuration Management**: Environment-specific settings
## Project Structure
```
├── ApiService/
│ ├── Controllers/ # API controllers
│ ├── Models/ # Data models
│ ├── Services/ # Business logic services
│ ├── Program.cs # Application entry point
│ └── Dockerfile # Container definition
├── Aspire.Customization.AppHost/
│ ├── Program.cs # Aspire application host
│ └── ResourceBuilderExtensions.cs
└── Aspire.Customization.ServiceDefaults/
└── Extensions.cs # Shared service configurations
```
## API Endpoints
### Weather Forecast Operations
- `GET /api/weatherforecast` - Get all weather forecasts
- `GET /api/weatherforecast/{date}` - Get a specific weather forecast
- `POST /api/weatherforecast` - Create a new weather forecast
- `PUT /api/weatherforecast/{date}` - Update an existing weather forecast
- `DELETE /api/weatherforecast/{date}` - Delete a weather forecast
### Health and Monitoring
- `GET /health` - Application health status
- `GET /alive` - Liveness probe
- `GET /swagger` - Swagger UI documentation
- `GET /scalar/v1` - Scalar API reference
- `GET /api-docs` - ReDoc documentation
## Getting Started
### Prerequisites
- .NET 9 SDK
- Docker (optional, for containerization)
### Running the Application
1. **Using .NET CLI**:
```bash
cd Aspire.Customization.AppHost
dotnet run
```
2. **Using Docker**:
```bash
docker-compose up
```
### Development
The project follows clean architecture principles with separation of concerns:
1. **Controllers**: Handle HTTP requests and responses
2. **Services**: Implement business logic
3. **Models**: Define data structures
4. **Extensions**: Provide reusable functionality
## Configuration
The application supports multiple environments through configuration files:
- `appsettings.json` - Base configuration
- `appsettings.Development.json` - Development environment
- `appsettings.Production.json` - Production environment (if created)
Key configuration sections include:
- **ApiSettings**: API metadata
- **HealthCheckSettings**: Health monitoring configuration
- **CorsSettings**: Cross-origin resource sharing settings
## Deployment
### Container Deployment
The application can be containerized using the provided Dockerfile:
```bash
# Build the image
docker build -t weather-api -f ApiService/Dockerfile .
# Run the container
docker run -p 8080:8080 weather-api
```
### Aspire Deployment
The Aspire application host provides orchestration capabilities for deploying the entire solution with dependent services.
## Best Practices Implemented
1. **Error Handling**: Comprehensive exception handling with proper HTTP status codes
2. **Logging**: Structured logging with appropriate levels
3. **Documentation**: XML documentation for all public APIs
4. **Health Monitoring**: Custom health checks with detailed reporting
5. **Security**: HTTPS enforcement and CORS configuration
6. **Performance**: Response compression and caching considerations
7. **Resilience**: Retry policies and circuit breaker patterns
8. **Observability**: OpenTelemetry integration for metrics and tracing
## Extending the Application
To add new features:
1. Create a new model in the `Models` folder
2. Define a service interface in the `Services` folder
3. Implement the service
4. Create a controller to expose the functionality
5. Register the service in `Program.cs`
6. Add appropriate tests
## Contributing
This project demonstrates enterprise-grade development practices. Contributions should follow the established patterns and include appropriate tests.
## License
This project is a demonstration and educational resource.