Skip to content

README.md

Latest commit

 

History

History
130 lines (92 loc) · 4.97 KB

README.md

File metadata and controls

130 lines (92 loc) · 4.97 KB

🍩 ApiGen

dotnet Release License: LGPL v3 Security Rating Maintainability Rating Coverage Lines of Code

ASP.NET microservice archetype generator for .NET 10. Point it at an OpenAPI spec and get a ready-to-run hexagonal architecture solution.

📦 What it generates

Given an OpenAPI document with extended annotations, ApiGen produces a fully structured .NET solution:

Layer Namespace Contents
Api {Project}.Api Controllers, Helpers, Middleware, Program.cs
Domain {Project}.Domain Models (DTOs), Services, Utils
Infrastructure {Project}.Infrastructure Entities, Repositories, DbContext
Tests {Project}.Domain.Tests Controller tests, Service tests

Inspired by apigen.springboot, adapted for the .NET ecosystem by CloudAPPi Services.

try api sample template

🚀 Quick start

dotnet cli

dotnet run --project ./src/Api/Api.csproj

docker

docker build -t apigen .
docker run -d -p 8080:8080 --name apigen apigen

docker-compose

docker-compose up --build -d

▶️ Usage

REST API

Once running, the Swagger UI is available at /swagger. You can also trigger generation directly via curl — see the example specs under src/Generator/Examples/.

curl -X 'POST' \
  'http://localhost:8080/generator/file' \
  -H 'accept: */*' \
  -H 'Content-Type: multipart/form-data' \
  -F 'file=@<openapi-file>'

CLI

Download the build or compile the Command project and run:

apigen <openapi-path>

⚙️ Configuration

🗄️ data-driver

Control the database provider via the data-driver field in the x-apigen-project OpenAPI extension:

Value NuGet package DbContext registration
(not set) Microsoft.EntityFrameworkCore.InMemory UseInMemoryDatabase(...)
postgresql Npgsql.EntityFrameworkCore.PostgreSQL UseNpgsql(...)
mysql Pomelo.EntityFrameworkCore.MySql UseMySql(..., ServerVersion.AutoDetect(...)) 
x-apigen-project:
  name: My Project
  description: ...
  version: 1.0.0
  data-driver: postgresql   # postgresql | mysql | (omit for in-memory)

The generated project includes only the required provider package. The connection string is read at runtime from the DATABASE_URL environment variable.

🏷️ OpenAPI extensions

ApiGen relies on custom extensions to enrich the generated code:

Extension Scope Purpose
x-apigen-project Document Project metadata and database driver
x-apigen-models Components Entity definitions with relational persistence mapping
x-apigen-mapping Schema DTO → Entity AutoMapper profile
x-apigen-binding Path Binds an endpoint group to a service

💿 ORM scaffolding from an existing database

If you prefer to scaffold entities from an existing database rather than defining them manually, use the EF Core CLI:

dotnet tool install --global dotnet-ef
dotnet ef dbcontext scaffold <connection-string> <driver> -o Infrastructure/Entities

Example with PostgreSQL:

dotnet ef dbcontext scaffold \
  "Host=<url>:<port>;Database=<db>;Username=<user>;Password=<pass>" \
  Npgsql.EntityFrameworkCore.PostgreSQL \
  -o Infrastructure/Entities