java.md

May 2, 2024 · View on GitHub

METADATA

PropertyValueNotes
generator namejavapass this to the generate command after -g
generator stabilitySTABLE
generator typeCLIENT
generator languageJava
generator language version17
generator default templating enginehandlebars
helpMsgGenerates a Java client library

Features in this generator:
- v3.0.0 - v3.1.0 OpenAPI Specification support
- Very thorough documentation generated in the style of javadocs
- Input types constrained for a Schema in SomeSchema.validate
- validate method can accept arbitrary List/Map/null/int/long/double/float/String json data
- Immutable List output classes generated and returned by validate for List<?> input
- Immutable Map output classes generated and returned by validate for Map<?, ?> input
- Strictly typed list input can be instantiated in client code using generated ListBuilders
- Strictly typed map input can be instantiated in client code using generated MapBuilders
- Sequential map builders are generated ensuring that required properties are set before build is invoked. Looks like:
- new MapBuilder().requiredA("a").requiredB("b").build()
- new MapBuilder().requiredA("a").requiredB("b").optionalProp("c").additionalProperty("someAddProp", "d").build()
- Run time type checking and validation when
- validating schema payloads
- instantiating List output class (validation run)
- instantiating Map output class (validation run)
- Note: if needed, validation of json schema keywords can be deactivated via a SchemaConfiguration class
- Enums classes are generated and may be input into Schema.validate or the List/MapBuilder add/setter methods
- The Checker-Framework's NullnessChecker and @Nullable annotations are used in the java client
- ensuring that null pointer exceptions will not happen
- Invalid (in java) property names supported like class, 1var, hi-there etc in
- component schema names
- schema property names (a fallback setter is written in the MapBuilder)
- Generated interfaces are largely consistent with the python code
- Openapi spec inline schemas supported at any depth in any location
- Format support for: int32, int64, float, double, date, datetime, uuid
- Payload values are not coerced when validated, so a date/date-time value can pass other validations that describe the payload only as type string
- enum types are generated for enums of type string/integer/number/boolean/null
- String transmission of numbers supported with type: string, format: number

CONFIG OPTIONS

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

OptionDescriptionValuesDefault
allowUnicodeIdentifiersboolean, toggles whether unicode identifiers are allowed in names or not, default is falsefalse
artifactDescriptionartifact description in generated pom.xmlOpenAPI Java
artifactUrlartifact URL in generated pom.xmlhttps://github.com/openapi-json-schema-tools/openapi-json-schema-generator
artifactVersionartifact version in generated pom.xml. This also becomes part of the generated library's filename1.0.0
buildToolthe build automation tool used in generated code
maven
Use maven
gradle
Use gradle
maven
developerEmaildeveloper email in generated pom.xmlteam@openapijsonschematools.org
developerNamedeveloper name in generated pom.xmlOpenAPI-Generator Contributors
developerOrganizationdeveloper organization in generated pom.xmlOpenAPITools.org
developerOrganizationUrldeveloper organization URL in generated pom.xmlhttp://openapijsonschematools.org
groupIdgroupId in generated pom.xmlorg.openapijsonschematools
invokerPackageroot package for generated codeorg.openapijsonschematools.client
licenseNameThe name of the licenseUnlicense
licenseUrlThe URL of the licensehttp://unlicense.org
parentArtifactIdparent artifactId in generated pom N.B. parentGroupId, parentArtifactId and parentVersion must all be specified for any of them to take effectnull
parentGroupIdparent groupId in generated pom N.B. parentGroupId, parentArtifactId and parentVersion must all be specified for any of them to take effectnull
parentVersionparent version in generated pom N.B. parentGroupId, parentArtifactId and parentVersion must all be specified for any of them to take effectnull
scmConnectionSCM connection in generated pom.xmlscm:git:git@github.com:openapi-json-schema-tools/openapi-json-schema-generator.git
scmDeveloperConnectionSCM developer connection in generated pom.xmlscm:git:git@github.com:openapi-json-schema-tools/openapi-json-schema-generator.git
scmUrlSCM URL in generated pom.xmlhttps://github.com/openapi-json-schema-tools/openapi-json-schema-generator
snapshotVersionUses a SNAPSHOT version.
true
Use a SnapShot Version
false
Use a Release Version
null
sourceFoldersource folder for generated codesrc/main/java
testOutputSet output folder for models and APIs tests${project.build.directory}/generated-test-sources/openapi

SUPPORTED VENDOR EXTENSIONS

Extension nameDescriptionApplicable forDefault value
x-enum-varnamesA list of strings that defines the enum variable names, must be adjacent to enumSCHEMA[]
x-enum-descriptionsA list of strings that defines the enum descriptions, must be adjacent to enumSCHEMA[]

INSTANTIATION TYPES

Type/AliasInstantiated By
arrayFrozenList
booleanboolean
integerNumber (int, long, float with integer values, double with integer values)
nullVoid (null)
numberNumber (int, long, float, double)
objectFrozenMap
stringString

LANGUAGE PRIMITIVES

  • Boolean
  • Double
  • Float
  • Integer
  • Long
  • Object
  • String
  • boolean
  • byte[]

RESERVED WORDS

  • abstract
  • apiclient
  • apiexception
  • apiresponse
  • assert
  • boolean
  • break
  • byte
  • case
  • catch
  • char
  • class
  • configuration
  • const
  • continue
  • default
  • do
  • double
  • else
  • enum
  • extends
  • final
  • finally
  • float
  • for
  • goto
  • if
  • implements
  • import
  • instanceof
  • int
  • integer
  • interface
  • linkedhashset
  • list
  • localdate
  • localreturntype
  • localvaraccept
  • localvaraccepts
  • localvarauthnames
  • localvarcollectionqueryparams
  • localvarcontenttype
  • localvarcontenttypes
  • localvarcookieparams
  • localvarformparams
  • localvarheaderparams
  • localvarpath
  • localvarpostbody
  • localvarqueryparams
  • long
  • map
  • native
  • new
  • null
  • number
  • package
  • private
  • protected
  • public
  • return
  • short
  • static
  • strictfp
  • string
  • stringutil
  • super
  • switch
  • synchronized
  • this
  • throw
  • throws
  • tostring
  • transient
  • try
  • uuid
  • void
  • volatile
  • while
  • zoneddatetime

FEATURE SET

Client Modification Feature

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

Components Feature

NameSupportedDefined By
schemas✓OAS3
responses✓OAS3
parameters✓OAS3
examples✗OAS3
requestBodies✓OAS3
headers✓OAS3
securitySchemes✓OAS3
links✗OAS3
callbacks✗OAS3
pathItems✗OAS3

Data Type Feature

NameSupportedDefined By
Custom✗OAS2,OAS3
Int32✓OAS2,OAS3
Int64✓OAS2,OAS3
Integer✓OAS2,OAS3
Float✓OAS2,OAS3
Double✓OAS2,OAS3
Number✓OAS2,OAS3
String✓OAS2,OAS3
Byte✗OAS2,OAS3
Binary✗OAS2,OAS3
Boolean✓OAS2,OAS3
Date✓OAS2,OAS3
DateTime✓OAS2,OAS3
Password✗OAS2,OAS3
File✗OAS2
Uuid✓OAS2,OAS3
Array✓OAS2,OAS3
Null✓OAS3
AnyType✓OAS2,OAS3
Object✓OAS2,OAS3
Enum✓OAS2,OAS3

Documentation Feature

NameSupportedDefined By
Readme✓ToolingExtension
Servers✓OAS3
Security✓OAS2,OAS3
ComponentSchemas✓OAS3
ComponentResponses✓OAS3
ComponentParameters✓OAS3
ComponentRequestBodies✓OAS3
ComponentHeaders✓OAS3
ComponentSecuritySchemes✓OAS3
ComponentLinks✗OAS3
ComponentCallbacks✗OAS3
ComponentPathItems✗OAS3
Api✓ToolingExtension

Global Feature

NameSupportedDefined By
Info✓OAS2,OAS3
Servers✓OAS3
Paths✓OAS2,OAS3
Webhooks✗OAS3
Components✓OAS3
Security✓OAS2,OAS3
Tags✗OAS2,OAS3
ExternalDocs✗OAS2,OAS3

Operation Feature

NameSupportedDefined By
Responses_HttpStatusCode✓OAS3
Responses_RangedResponseCodes✓OAS3
Responses_Default✓OAS3
Responses_RedirectionResponse✓OAS3
Security✓OAS2,OAS3
Servers✓OAS3

Parameter Feature

NameSupportedDefined By
Name✗OAS2,OAS3
Required✗OAS2,OAS3
In_Path✗OAS2,OAS3
In_Query✗OAS2,OAS3
In_Header✗OAS2,OAS3
In_Cookie✗OAS3
Style_Matrix✗OAS3
Style_Label✗OAS3
Style_Form✗OAS3
Style_Simple✗OAS3
Style_SpaceDelimited✗OAS3
Style_PipeDelimited✗OAS3
Style_DeepObject✗OAS3
Explode✗OAS3
Schema✗OAS3
Content✗OAS3

Schema Feature

NameSupportedDefined By
AdditionalProperties✓OAS2,OAS3
AllOf✓OAS2,OAS3
AnyOf✓OAS3
Const✓OAS3
Contains✓OAS3
Default✓OAS2,OAS3
DependentRequired✓OAS3
DependentSchemas✓OAS3
Discriminator✗OAS2,OAS3
Else✓OAS3
Enum✓OAS2,OAS3
ExclusiveMinimum✓OAS2,OAS3
ExclusiveMaximum✓OAS2,OAS3
Format✓OAS2,OAS3
If✓OAS3
Items✓OAS2,OAS3
MaxContains✓OAS3
MaxItems✓OAS2,OAS3
MaxLength✓OAS2,OAS3
MaxProperties✓OAS2,OAS3
Maximum✓OAS2,OAS3
MinContains✓OAS3
MinItems✓OAS2,OAS3
MinLength✓OAS2,OAS3
MinProperties✓OAS2,OAS3
Minimum✓OAS2,OAS3
MultipleOf✓OAS2,OAS3
Not✓OAS3
Nullable✓OAS3
OneOf✓OAS3
Pattern✓OAS2,OAS3
PatternProperties✓OAS3
PrefixItems✓OAS3
Properties✓OAS2,OAS3
PropertyNames✓OAS3
Ref✓OAS2,OAS3
Required✓OAS2,OAS3
Then✓OAS3
Type✓OAS2,OAS3
UnevaluatedItems✓OAS3
UnevaluatedProperties✓OAS3
UniqueItems✓OAS2,OAS3
Xml✗OAS2,OAS3

Security Feature

NameSupportedDefined By
HTTP_Basic✓OAS2,OAS3
ApiKey✓OAS2,OAS3
OpenIDConnect✗OAS3
HTTP_Bearer✓OAS2,OAS3
OAuth2_Implicit✗OAS2,OAS3
OAuth2_Password✗OAS2,OAS3
OAuth2_ClientCredentials✗OAS2,OAS3
OAuth2_AuthorizationCode✗OAS2,OAS3

Wire Format Feature

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