🍩 ApiGen

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.

---

🚀 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

---