apigenie-generator server aspnet
Tier 1 · Release 0.12.0: Level 1 ✓ · Level 2 ✓ · Level 3 ✓ · Verification
Generate an ASP.NET Core server in C#, built on Minimal APIs.
From an AsyncAPI document, the command generates an ASP.NET Core Kafka application instead; see
apigenie-generator server aspnet (AsyncAPI).
Usage
apigenie-generator server aspnet [...OPTIONS] INPUT_FILE
Description
The input must be an OpenAPI 3.0, 3.1 or 3.2 document or, since 0.12.0, a Swagger 2.0 document (see
Swagger 2.0 input); bundle documents referencing other
files with apigenie bundle.
The generated project targets .NET 8 (or 9 and 10, see target_framework) and uses only the
shared framework, without NuGet packages:
PetStore.csproj
Program.cs the host, written only when missing
README.md
ApiRegistration.cs MapPetStoreApi(): maps the endpoints of all operations
Apis/IPetsApi.cs one interface per group of operations
Apis/PetsApi.cs its implementation, written only when missing
Endpoints/PetsEndpoints.cs routes, parameter binding, validation and metadata
Models/Pet.cs records and enums of the schemas
Senders/*.cs typed HTTP clients sending the webhooks and callbacks
Infrastructure/*.cs helpers used by the generated code
Operations are grouped by their first tag (or by the first segment of their paths). Each group gets an interface whose methods return the responses of the operation as a union of typed results, so the compiler accepts only declared responses:
public interface IPetsApi
{
/// <summary>Find a pet</summary>
/// <remarks>GET /pets/{petId}</remarks>
Task<Results<Ok<Pet>, NotFound, GoneResult<Error>>> GetPet(long petId, CancellationToken cancellationToken);
}
Implementations return TypedResults.Ok(pet), TypedResults.NotFound() and the like. Statuses
without a TypedResults method (403, 410, 429, 500, …) have result types of their own, created
with ApiResults.Gone(error). All results describe their responses in the endpoint metadata, so
OpenAPI documents produced by ASP.NET Core match the input.
Since 0.12.0, a response with several media types has a result for each kind, and the
implementation picks one, e.g. by the Accept header of the request. Files (PDF, PNG, …) are
FileStreamHttpResult, text is ContentHttpResult. text/event-stream is
ServerSentEventsHttpResult<T>, and JSON Lines (application/jsonl and the like) is
JsonLinesHttpResult<T>. The streams are typed by the item schema: OpenAPI 3.2 itemSchema, or
x-itemSchema, and for events the contentSchema of their data. Create them with
StreamingResults.ServerSentEvents(events) from an IAsyncEnumerable<ServerSentEvent<T>>, and
with StreamingResults.JsonLines(items) from an IAsyncEnumerable<T>. Both write and flush each
item as it comes. Pass statusCode when the response the document declares the stream for isn’t
200, and contentType for another JSON Lines media type.
The endpoints bind parameters from the path, the query, headers and cookies, in the styles of the document, e.g. exploded or delimited arrays. They read JSON, text, binary, form and multipart bodies, and resolve the implementation from the services of the request. Since 0.12.0, they also read:
- objects in the query, as
deepObject, exploded form, or comma-separated keys and values; - parameters described by JSON or text
content; - form fields with the
deepObjectencoding; - file arrays whose items have
format: binaryor acontentMediaType.
var app = builder.Build();
app.MapPetStoreApi();
Models are records with required properties, System.Text.Json attributes and DataAnnotations
attributes for the constraints of the schemas (minimum, maxLength, pattern, format: email,
maxItems, …). An endpoint filter checks them, and the values of enums, before the
implementation is called, and answers invalid requests with 400 validation problem details.
oneOfandanyOfwith a discriminator become abstract records with[JsonPolymorphic]attributes, and their variants derive from them. On .NET 8, System.Text.Json reads the discriminator only as the first property of an object.allOfreferencing a schema with a discriminator becomes inheritance; otherallOfschemas are merged into one record.- String enums become C# enums whose converters read and write the values of the document, e.g.
in-progress. Integer enums keep their values. Thex-enum-varnamesextension names members. - Inline object and enum schemas get types named after their location, e.g.
PetOwnerfor theownerproperty ofPet. Identical inline schemas share a type. - Schemas whose names would clash with types of .NET (
Task,File,Environment, …) get aModelsuffix. - Since 0.12.0, tuples (
prefixItems),patternProperties,multipleOf, andif/then/else,dependentRequiredanddependentSchemasconditions are written as forapigenie-generator client csharp. They become lists, dictionaries or records withEntries,[MultipleOf]attributes, andIValidatableObjectimplementations, which the endpoint filter checks.
Operations with security requirements call RequireAuthorization(); configure the authentication
schemes in Program.cs, which lists the schemes of the document. Since 0.12.0, when each
alternative of the requirements lists OAuth 2.0 or OpenID Connect scopes, the endpoint answers
403 unless the user has every scope of one alternative. The scopes are read from the scope, scp
or Microsoft Entra ID scope claims (ScopeAuthorization).
Since 0.12.0, operations or paths with servers of their own are mapped below the path of their
first server, with the defaults of its variables, instead of below the first server of the
document. For example, GET /health of a server https://status.example.com is mapped at
/health. MapPetStoreApi() maps them outside the group it returns, so conventions added to
that group, e.g. RequireCors(), don’t apply to them. With base_path: none they have no prefix
either.
Since 0.12.0, webhooks and callbacks get senders in Senders/. They are typed HTTP clients:
WebhookSenderhas a method per webhook.- Each callback of an operation has a class, e.g.
CreateShipmentStatusChangedCallback, with a method per request.
Register them with builder.Services.AddHttpClient<WebhookSender>() and one call per callback
class; a new Program.cs has these calls. The methods take the URL, which the caller resolves:
the subscriber’s, or the value the callback’s expression names, e.g. callbackUrl of the request
body. Then they take the parameters and the body. They send JSON bodies with the JSON options of
the application, and return the HttpResponseMessage.
Not supported:
oneOfandanyOfwithout a discriminator whose members have different types (typedobject; members of one type, e.g. strings of different formats, give that type), andnotother than on the presence and constant values of properties;- separate request and response variants of models with
readOnlyandwriteOnlyproperties (such properties are optional); - conditions on anything other than the presence and constant values of properties, and
unevaluatedProperties; - in parameters, arrays of objects, objects in the label or matrix style, maps in the exploded
form style, and
contentother than JSON or text (left out with a warning); - the constraints of form fields, and response headers;
- request bodies of more than one kind, e.g. CSV or JSON Lines: the preferred one is accepted;
- the host of an operation’s own server: its routes answer on every host;
- scopes, when an alternative of the requirements lists no OAuth 2.0 or OpenID Connect scopes
(e.g. an API key), and the roles that OpenAPI 3.1 lists for other schemes: the endpoint only
calls
RequireAuthorization(); - in the senders of webhooks and callbacks, path, object and
contentparameters, theAccept,Content-TypeandAuthorizationheader parameters, and form bodies (left out with a warning).
Extensions
| Extension | Effect |
|---|---|
x-apigenie.codegen.controller-name |
on an operation or its path item: the group (API interface) of the operation, whatever grouping says |
x-apigenie.codegen.action-name |
name of the method of an operation, when action_naming lists extension |
x-apigenie.codegen.disabled |
true on an operation or its path item leaves the operation out, unless skip_disabled is false |
x-internal |
true on an operation leaves it out |
x-enum-varnames, x-enum-names |
names of the members of an enum, in PascalCase |
x-enum-descriptions, x-enumDescriptions |
documentation comments of the members of an enum |
x-defaultMapping |
defaultMapping of a discriminator in OpenAPI 3.0 and 3.1 documents: the schema of the values whose discriminator value isn’t mapped |
x-itemSchema |
itemSchema of a media type in OpenAPI 3.0 and 3.1 documents: the type of the items of a streamed response |
The extensions can live in an overlay for this target instead of in the document, e.g.
aspnet.overlay.yaml:
overlay: 1.0.0
info:
title: ASP.NET names
version: 1.0.0
actions:
- target: $.components.schemas.PetStatus
update:
x-enum-varnames: [Available, OnHold, Sold]
- target: $.paths['/pets']
update:
x-apigenie:
codegen:
controller-name: Animals
apigenie-generator server aspnet openapi.yaml --overlay aspnet.overlay.yaml -o out
Options
-c, –config
Path to the configuration file to use. See the “Configuration” section for more information.
–overlay OVERLAY
Path to an OpenAPI Overlay (1.0 to 1.2) applied to the input before generating, e.g. one setting the
extensions of the “Extensions” section. Can be repeated: the overlays apply in order, after those
listed under commands.generate.server_aspnet.overlay in the configuration file (with paths
relative to it). Warnings and errors about a value an overlay set point to the overlay.
–strict
Makes an overlay action whose target selects nothing an error (exit status 2, nothing is generated)
instead of a warning (OVERLAY:LINE:COL: action #N (TARGET) selects no nodes.).
–check
Writes nothing: compares what the generator would write with the output directory, prints the files that would be created or changed, and exits with 1 when there are any (since 0.12.0). See Check that generated code is up to date.
-o, –output
Directory where the project is generated.
–package-name
Root namespace of the generated code, e.g. Acme.PetStore; also the name of the project.
Defaults to the title of the API.
–package-version
Version of the project. Defaults to the version of the API when it’s a valid .NET version, or
1.0.0.
-p, –property NAME=VALUE
Sets an option (see below), e.g. -p layout=sources; can be repeated. Options given on the
command line take precedence over the configuration file. OpenAPI documents only: using it with an
AsyncAPI document is an error.
Configuration
The options are read from commands.generate.server_aspnet. Its asyncapi section configures
the generation from AsyncAPI documents (see
apigenie-generator server aspnet (AsyncAPI)).
version: '1.0'
commands:
generate:
server_aspnet:
namespace: Acme.PetStore
target_framework: net10.0
grouping: url
| Option | Values | Description |
|---|---|---|
layout |
project, sources |
project (default): a complete project (.csproj, Program.cs, README.md); sources: only the generated sources, for an existing project |
namespace |
namespace | Root namespace of the generated code (also --package-name); derived from the API title by default |
target_framework |
net8.0, net9.0, net10.0 |
Target framework of the project (default: net8.0) |
grouping |
tag, url |
Grouping of operations into API interfaces: by their first tag (default), or by the first segment of their paths |
action_naming |
id, extension, url |
Sources of method names, in order of preference (default: id, url) |
validation |
filter, none |
filter (default): an endpoint filter validates parameters and bodies against their DataAnnotations; none: attributes only |
authorization |
require, none |
require (default): operations with security requirements call RequireAuthorization(); none: no authorization metadata |
base_path |
servers, none |
servers (default): routes are prefixed with the path of the first server URL, or of the first own server of the operation or its path; none: no prefix |
program |
true, false |
Generate Program.cs and stub implementations of the API interfaces (written only when missing; default: true) |
skip_deprecated |
true, false |
Don’t generate deprecated operations (default: false) |
skip_disabled |
true, false |
Don’t generate operations disabled with the x-apigenie extension (default: true) |
model_suffix |
text | Suffix of model names, e.g. Dto |
version |
version | Version of the project (also --package-version); defaults to the version of the API |
Unknown options are errors.
Verification
The codegen conformance suite runs this target on the Carpet Express OpenAPI fixture. Level 1 compares the output with its snapshots and checks each feature, Level 2 runs the language's type checker and linter, and Level 3 runs the generated code in contract tests against the fixture. All targets.
This target's support tier is Tier 1. It goes through all three levels before every release, with the goal of supporting every feature of the fixture. Its unsupported features are worked on first.
| Results | Level 1 | Level 2 | Level 3 |
|---|---|---|---|
| Release 0.12.0 | ✓ snapshots of 3.2, 3.1, 3.0, 2.0; 3.2: 39 supported, 0 not yet | ✓ pass (.NET SDK 8.0.204) | ✓ 70 of 77 operations pass, 2 known failures (dotnet) |
| Development version | ✓ snapshots of 3.2, 3.1, 3.0, 2.0; 3.2: 39 supported, 0 not yet | runs before a release | runs before a release, 2 known failures |