ContextQMD
Back to Openapi Generator

Documentation for the aspnetcore Generator

docs/generators/aspnetcore.md

7.22.010.8 KB
Original Source

METADATA

PropertyValueNotes
generator nameaspnetcorepass this to the generate command after -g
generator stabilitySTABLE
generator typeSERVER
generator languageC#
generator default templating enginemustache
helpTxtGenerates an ASP.NET Core Web API server.

CONFIG OPTIONS

These options may be applied as additional-properties (cli) or configOptions (plugins). Refer to configuration docs for more details.

OptionDescriptionValuesDefault
aspnetCoreVersionASP.NET Core version: 6.0, 5.0, 3.1, 3.0, 2.2, 2.1, 2.0 (deprecated)<dl><dt>2.0</dt><dd>ASP.NET Core 2.0</dd><dt>2.1</dt><dd>ASP.NET Core 2.1</dd><dt>2.2</dt><dd>ASP.NET Core 2.2</dd><dt>3.0</dt><dd>ASP.NET Core 3.0</dd><dt>3.1</dt><dd>ASP.NET Core 3.1</dd><dt>5.0</dt><dd>ASP.NET Core 5.0</dd><dt>6.0</dt><dd>ASP.NET Core 6.0</dd><dt>7.0</dt><dd>ASP.NET Core 7.0</dd><dt>8.0</dt><dd>ASP.NET Core 8.0</dd></dl>8.0
buildTargetTarget to build an application or library<dl><dt>program</dt><dd>Generate code for a standalone server</dd><dt>library</dt><dd>Generate code for a server abstract class library</dd></dl>program
centralizedPackageVersionManagementOption to control the usage of centralized package version management. https://devblogs.microsoft.com/nuget/introducing-central-package-management/#disabling-central-package-management<dl><dt>optout</dt><dd>Opt out of centralized package version management. Set this if you have a Directory.Packages.pros file but want this project to ignore it.</dd><dt>default</dt><dd>Property in project won't be used</dd><dt>enable</dt><dd>Centralized package version management will be used</dd></dl>null
classModifierClass Modifier for controller classes: Empty string or abstract.
compatibilityVersionASP.Net Core CompatibilityVersionVersion_2_2
enumNameSuffixSuffix that will be appended to all enum names.Enum
enumValueSuffixSuffix that will be appended to all enum values.Enum
generateBodyGenerates method body.true
isLibraryIs the build a libraryfalse
licenseNameThe name of the licenseNoLicense
licenseUrlThe URL of the licensehttp://localhost
modelClassModifierModel Class Modifier can be nothing or partialpartial
newtonsoftVersionVersion for Microsoft.AspNetCore.Mvc.NewtonsoftJson for ASP.NET Core 3.0+3.0.0
nullableReferenceTypesUse nullable annotations in the project. Only supported on C# 8 / ASP.NET Core 3.1 or newer.false
operationIsAsyncSet methods to async or sync (default).false
operationModifierOperation Modifier can be virtual or abstract<dl><dt>virtual</dt><dd>Keep method virtual</dd><dt>abstract</dt><dd>Make method abstract</dd></dl>virtual
operationResultTaskSet methods result to Task<>.false
packageAuthorsSpecifies Authors property in the .NET Core project file.OpenAPI
packageCopyrightSpecifies an AssemblyCopyright for the .NET Framework global assembly attributes stored in the AssemblyInfo file.No Copyright
packageDescriptionSpecifies a AssemblyDescription for the .NET Framework global assembly attributes stored in the AssemblyInfo file.A library generated from a OpenAPI doc
packageGuidThe GUID that will be associated with the C# projectnull
packageNameC# package name (convention: Title.Case).Org.OpenAPITools
packageTitleSpecifies an AssemblyTitle for the .NET Framework global assembly attributes stored in the AssemblyInfo file.OpenAPI Library
packageVersionC# package version.1.0.0
pocoModelsBuild POCO Modelsfalse
returnICollectionReturn ICollection<T> instead of the concrete type.false
sortParamsByRequiredFlagSort method arguments to place required parameters before optional parameters.true
sourceFoldersource folder for generated codesrc
swashbuckleVersionSwashbuckle version: 3.0.0 (deprecated), 4.0.0 (deprecated), 5.0.0 (deprecated), 6.4.0<dl><dt>3.0.0</dt><dd>Swashbuckle 3.0.0</dd><dt>4.0.0</dt><dd>Swashbuckle 4.0.0</dd><dt>5.0.0</dt><dd>Swashbuckle 5.0.0</dd><dt>6.4.0</dt><dd>Swashbuckle 6.4.0</dd></dl>6.4.0
useCollectionDeserialize array types to Collection<T> instead of List<T>.false
useDateTimeForDateUse DateTime to model date properties even if DateOnly supported. (.net 6.0+ only)false
useDateTimeOffsetUse DateTimeOffset to model date-time propertiesfalse
useDefaultRoutingUse default routing for the ASP.NET Core version.true
useFrameworkReferenceUse frameworkReference for ASP.NET Core 3.0+ and PackageReference ASP.NET Core 2.2 or earlier.false
useNewtonsoftUses the Newtonsoft JSON library.true
useSeparateModelProjectCreate a separate project for modelsfalse
useSwashbuckleUses the Swashbuckle.AspNetCore NuGet package for documentation.true

SUPPORTED VENDOR EXTENSIONS

Extension nameDescriptionApplicable forDefault value
x-zero-based-enumWhen used on an enum, the index will not be generated and the default numbering will be used, zero-basedMODELfalse

IMPORT MAPPING

Type/AliasImports

INSTANTIATION TYPES

Type/AliasInstantiated By
arrayList
listList
mapDictionary

LANGUAGE PRIMITIVES

<ul class="column-ul"> <li>Boolean</li> <li>Collection</li> <li>DateOnly</li> <li>DateOnly?</li> <li>DateTime</li> <li>DateTime?</li> <li>DateTimeOffset</li> <li>DateTimeOffset?</li> <li>Decimal</li> <li>Dictionary</li> <li>Double</li> <li>Float</li> <li>Guid</li> <li>Guid?</li> <li>ICollection</li> <li>Int32</li> <li>Int64</li> <li>List</li> <li>Object</li> <li>String</li> <li>System.IO.Stream</li> <li>bool</li> <li>bool?</li> <li>byte[]</li> <li>decimal</li> <li>decimal?</li> <li>double</li> <li>double?</li> <li>float</li> <li>float?</li> <li>int</li> <li>int?</li> <li>long</li> <li>long?</li> <li>string</li> <li>uint</li> <li>uint?</li> <li>ulong</li> <li>ulong?</li> </ul>

RESERVED WORDS

<ul class="column-ul"> <li>Client</li> <li>Configuration</li> <li>Environment</li> <li>OperatingSystem</li> <li>TimeZone</li> <li>Version</li> <li>abstract</li> <li>as</li> <li>async</li> <li>await</li> <li>base</li> <li>bool</li> <li>break</li> <li>byte</li> <li>case</li> <li>catch</li> <li>char</li> <li>checked</li> <li>class</li> <li>client</li> <li>const</li> <li>continue</li> <li>decimal</li> <li>default</li> <li>delegate</li> <li>do</li> <li>double</li> <li>dynamic</li> <li>else</li> <li>enum</li> <li>event</li> <li>explicit</li> <li>extern</li> <li>false</li> <li>finally</li> <li>fixed</li> <li>float</li> <li>for</li> <li>foreach</li> <li>goto</li> <li>if</li> <li>implicit</li> <li>in</li> <li>int</li> <li>interface</li> <li>internal</li> <li>is</li> <li>localVarFileParams</li> <li>localVarFormParams</li> <li>localVarHeaderParams</li> <li>localVarHttpContentType</li> <li>localVarHttpContentTypes</li> <li>localVarHttpHeaderAccept</li> <li>localVarHttpHeaderAccepts</li> <li>localVarPath</li> <li>localVarPathParams</li> <li>localVarPostBody</li> <li>localVarQueryParams</li> <li>localVarResponse</li> <li>localVarStatusCode</li> <li>lock</li> <li>long</li> <li>namespace</li> <li>new</li> <li>null</li> <li>object</li> <li>operator</li> <li>out</li> <li>override</li> <li>parameter</li> <li>params</li> <li>private</li> <li>protected</li> <li>public</li> <li>readonly</li> <li>ref</li> <li>return</li> <li>sbyte</li> <li>sealed</li> <li>short</li> <li>sizeof</li> <li>stackalloc</li> <li>static</li> <li>string</li> <li>struct</li> <li>switch</li> <li>system</li> <li>this</li> <li>throw</li> <li>true</li> <li>try</li> <li>typeof</li> <li>uint</li> <li>ulong</li> <li>unchecked</li> <li>unsafe</li> <li>ushort</li> <li>using</li> <li>var</li> <li>virtual</li> <li>void</li> <li>volatile</li> <li>while</li> <li>yield</li> </ul>

FEATURE SET

Client Modification Feature

NameSupportedDefined By
BasePath✗ToolingExtension
Authorizations✗ToolingExtension
UserAgent✗ToolingExtension
MockServer✗ToolingExtension

Data Type Feature

NameSupportedDefined By
Custom✗OAS2,OAS3
Int32✓OAS2,OAS3
Int64✓OAS2,OAS3
Float✓OAS2,OAS3
Double✓OAS2,OAS3
Decimal✓ToolingExtension
String✓OAS2,OAS3
Byte✓OAS2,OAS3
Binary✓OAS2,OAS3
Boolean✓OAS2,OAS3
Date✓OAS2,OAS3
DateTime✓OAS2,OAS3
Password✓OAS2,OAS3
File✓OAS2
Uuid✗
Array✓OAS2,OAS3
Null✗OAS3
AnyType✗OAS2,OAS3
Object✓OAS2,OAS3
Maps✓ToolingExtension
CollectionFormat✓OAS2
CollectionFormatMulti✓OAS2
Enum✓OAS2,OAS3
ArrayOfEnum✓ToolingExtension
ArrayOfModel✓ToolingExtension
ArrayOfCollectionOfPrimitives✓ToolingExtension
ArrayOfCollectionOfModel✓ToolingExtension
ArrayOfCollectionOfEnum✓ToolingExtension
MapOfEnum✓ToolingExtension
MapOfModel✓ToolingExtension
MapOfCollectionOfPrimitives✓ToolingExtension
MapOfCollectionOfModel✓ToolingExtension
MapOfCollectionOfEnum✓ToolingExtension

Documentation Feature

NameSupportedDefined By
Readme✓ToolingExtension
Model✓ToolingExtension
Api✓ToolingExtension

Global Feature

NameSupportedDefined By
Host✓OAS2,OAS3
BasePath✓OAS2,OAS3
Info✓OAS2,OAS3
Schemes✗OAS2,OAS3
PartialSchemes✓OAS2,OAS3
Consumes✓OAS2
Produces✓OAS2
ExternalDocumentation✓OAS2,OAS3
Examples✓OAS2,OAS3
XMLStructureDefinitions✗OAS2,OAS3
MultiServer✗OAS3
ParameterizedServer✗OAS3
ParameterStyling✗OAS3
Callbacks✗OAS3
LinkObjects✗OAS3

Parameter Feature

NameSupportedDefined By
Path✓OAS2,OAS3
Query✓OAS2,OAS3
Header✓OAS2,OAS3
Body✓OAS2
FormUnencoded✓OAS2
FormMultipart✓OAS2
Cookie✓OAS3

Schema Support Feature

NameSupportedDefined By
Simple✓OAS2,OAS3
Composite✓OAS2,OAS3
Polymorphism✓OAS2,OAS3
Union✗OAS3
allOf✗OAS2,OAS3
anyOf✗OAS3
oneOf✗OAS3
not✗OAS3

Security Feature

NameSupportedDefined By
BasicAuth✓OAS2,OAS3
ApiKey✓OAS2,OAS3
OpenIDConnect✗OAS3
BearerToken✓OAS3
OAuth2_Implicit✗OAS2,OAS3
OAuth2_Password✗OAS2,OAS3
OAuth2_ClientCredentials✗OAS2,OAS3
OAuth2_AuthorizationCode✗OAS2,OAS3
SignatureAuth✗OAS3
AWSV4Signature✗ToolingExtension

Wire Format Feature

NameSupportedDefined By
JSON✓OAS2,OAS3
XML✓OAS2,OAS3
PROTOBUF✗ToolingExtension
Custom✗OAS2,OAS3