loafle/openapi-generator-original
3
0
Fork 1
mirror of https://github.com/OpenAPITools/openapi-generator.git synced 2025-11-04 02:33:54 +00:00
Code Issues Packages Projects Releases Wiki Activity
openapi-generator-original/docs/generators/kotlin.md
Łukasz Suski d02c0f493e
[Kotlin] [Retrofit2] [Coroutines] [Client] Option to remove Response<> wrapper in operation return types (#20613) 
* Add useResponseAsReturnType option to kotlin, jvm-retrofit2 and coroutines api template (#15491)

* Add useResponseAsReturnType flag to kotlin-jvm-retrofit2-coroutines.yaml sample

* Generate sample
2025-04-25 08:45:47 +01:00

12 KiB
Raw Blame History

title
Documentation for the kotlin Generator

METADATA

Property Value Notes
generator name kotlin pass this to the generate command after -g
generator stability STABLE
generator type CLIENT
generator language Kotlin
generator default templating engine mustache
helpTxt Generates a Kotlin client.

CONFIG OPTIONS

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

Option Description Values Default
additionalModelTypeAnnotations Additional annotations for model type(class level annotations). List separated by semicolon(;) or new line (Linux or Windows) null
apiSuffix suffix for api classes Api
artifactId Generated artifact id (name of jar). kotlin-client
artifactVersion Generated artifact's package version. 1.0.0
collectionType Option. Collection type to use
array
kotlin.Array
list
kotlin.collections.List
 list
dateLibrary Option. Date library to use
threetenbp-localdatetime
Threetenbp - Backport of JSR310 (jvm only, for legacy app only)
kotlinx-datetime
kotlinx-datetime (preferred for multiplatform)
string
String
java8-localdatetime
Java 8 native JSR310 (jvm only, for legacy app only)
java8
Java 8 native JSR310 (jvm only, preferred for jdk 1.8+)
threetenbp
Threetenbp - Backport of JSR310 (jvm only, preferred for jdk < 1.8)
 java8
enumPropertyNaming Naming convention for enum properties: 'camelCase', 'PascalCase', 'snake_case', 'UPPERCASE', and 'original' original
explicitApi Generates code with explicit access modifiers to comply with Kotlin Explicit API Mode. false
failOnUnknownProperties Fail Jackson de-serialization on unknown properties false
generateOneOfAnyOfWrappers Generate oneOf, anyOf schemas as wrappers. Only jvm-retrofit2(library), gson(serializationLibrary) support this option. false
generateRoomModels Generate Android Room database models in addition to API models (JVM Volley library only) false
groupId Generated artifact package's organization (i.e. maven groupId). org.openapitools
idea Add IntelliJ Idea plugin and mark Kotlin main and test folders as source folders. false
library Library template (sub-template) to use
jvm-ktor
Platform: Java Virtual Machine. HTTP client: Ktor 1.6.7. JSON processing: Gson, Jackson (default).
jvm-okhttp4
[DEFAULT] Platform: Java Virtual Machine. HTTP client: OkHttp 4.2.0 (Android 5.0+ and Java 8+). JSON processing: Moshi 1.8.0.
jvm-spring-webclient
Platform: Java Virtual Machine. HTTP: Spring 5 (or 6 with useSpringBoot3 enabled) WebClient. JSON processing: Jackson.
jvm-spring-restclient
Platform: Java Virtual Machine. HTTP: Spring 6 RestClient. JSON processing: Jackson.
jvm-retrofit2
Platform: Java Virtual Machine. HTTP client: Retrofit 2.6.2.
multiplatform
Platform: Kotlin multiplatform. HTTP client: Ktor 1.6.7. JSON processing: Kotlinx Serialization: 1.2.1.
jvm-volley
Platform: JVM for Android. HTTP client: Volley 1.2.1. JSON processing: gson 2.8.9
jvm-vertx
Platform: Java Virtual Machine. HTTP client: Vert.x Web Client. JSON processing: Moshi, Gson or Jackson.
 jvm-okhttp4
mapFileBinaryToByteArray Map File and Binary to ByteArray (default: false) false
modelMutable Create mutable models false
moshiCodeGen Whether to enable codegen with the Moshi library. Refer to the official Moshi doc for more info. false
nonPublicApi Generates code with reduced access modifiers; allows embedding elsewhere without exposing non-public API calls to consumers. false
nullableReturnType Nullable return type false
omitGradlePluginVersions Whether to declare Gradle plugin versions in build files. false
omitGradleWrapper Whether to omit Gradle wrapper for creating a sub project. false
packageName Generated artifact package name. org.openapitools.client
parcelizeModels toggle "@Parcelize" for generated models null
requestDateConverter JVM-Option. Defines in how to handle date-time objects that are used for a request (as query or parameter)
toJson
[DEFAULT] Date formatter option using a json converter.
toString
Use the 'toString'-method of the date-time object to retrieve the related string representation.
 toJson
serializableModel boolean - toggle "implements Serializable" for generated models null
serializationLibrary What serialization library to use: 'moshi' (default), or 'gson' or 'jackson' or 'kotlinx_serialization' moshi
sortModelPropertiesByRequiredFlag Sort model properties to place required parameters before optional parameters. null
sortParamsByRequiredFlag Sort method arguments to place required parameters before optional parameters. null
sourceFolder source folder for generated code src/main/kotlin
supportAndroidApiLevel25AndBelow [WARNING] This flag will generate code that has a known security vulnerability. It uses kotlin.io.createTempFile instead of java.nio.file.Files.createTempFile in order to support Android API level 25 and below. For more info, please check the following links https://github.com/OpenAPITools/openapi-generator/security/advisories/GHSA-23x4-m842-fmwf, https://github.com/OpenAPITools/openapi-generator/pull/9284 false
useCoroutines Whether to use the Coroutines adapter with the retrofit2 library. false
useNonAsciiHeaders Allow to use non-ascii headers with the okhttp library false
useResponseAsReturnType When using retrofit2 and coroutines, use Response<T> as return type instead of T. true
useRxJava3 Whether to use the RxJava3 adapter with the retrofit2 library. false
useSettingsGradle Whether the project uses settings.gradle. false
useSpringBoot3 Whether to use the Spring Boot 3 with the jvm-spring-webclient library. false

SUPPORTED VENDOR EXTENSIONS

Extension name Description Applicable for Default value
x-class-extra-annotation List of custom annotations to be added to model MODEL null
x-field-extra-annotation List of custom annotations to be added to property FIELD, OPERATION_PARAMETER null

IMPORT MAPPING

Type/Alias Imports
BigDecimal java.math.BigDecimal
Date java.time.LocalDate
DateTime java.time.OffsetDateTime
File java.io.File
LocalDate java.time.LocalDate
LocalDateTime java.time.LocalDateTime
LocalTime java.time.LocalTime
Timestamp java.sql.Timestamp
URI java.net.URI
UUID java.util.UUID

INSTANTIATION TYPES

Type/Alias Instantiated By
array kotlin.collections.ArrayList
list kotlin.collections.ArrayList
map kotlin.collections.HashMap

LANGUAGE PRIMITIVES

  • kotlin.Array
  • kotlin.Boolean
  • kotlin.Byte
  • kotlin.ByteArray
  • kotlin.Char
  • kotlin.Double
  • kotlin.Float
  • kotlin.Int
  • kotlin.Long
  • kotlin.Short
  • kotlin.String
  • kotlin.collections.List
  • kotlin.collections.Map
  • kotlin.collections.MutableList
  • kotlin.collections.MutableMap
  • kotlin.collections.MutableSet
  • kotlin.collections.Set

RESERVED WORDS

  • ApiResponse
  • abstract
  • actual
  • annotation
  • as
  • break
  • class
  • companion
  • const
  • constructor
  • continue
  • contract
  • crossinline
  • data
  • delegate
  • do
  • dynamic
  • else
  • enum
  • expect
  • external
  • false
  • field
  • final
  • finally
  • for
  • fun
  • if
  • import
  • in
  • infix
  • init
  • inline
  • inner
  • interface
  • internal
  • is
  • it
  • lateinit
  • noinline
  • null
  • object
  • open
  • operator
  • out
  • override
  • package
  • param
  • private
  • property
  • protected
  • public
  • receiver
  • reified
  • return
  • sealed
  • setparam
  • super
  • suspend
  • tailrec
  • this
  • throw
  • true
  • try
  • typealias
  • typeof
  • val
  • value
  • var
  • vararg
  • when
  • where
  • while

FEATURE SET

Client Modification Feature

Name Supported Defined By
BasePath ✓ ToolingExtension
Authorizations ✗ ToolingExtension
UserAgent ✗ ToolingExtension
MockServer ✗ ToolingExtension

Data Type Feature

Name Supported Defined 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

Name Supported Defined By
Readme ✓ ToolingExtension
Model ✓ ToolingExtension
Api ✓ ToolingExtension

Global Feature

Name Supported Defined 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

Name Supported Defined By
Path ✓ OAS2,OAS3
Query ✓ OAS2,OAS3
Header ✓ OAS2,OAS3
Body ✓ OAS2
FormUnencoded ✓ OAS2
FormMultipart ✓ OAS2
Cookie ✗ OAS3

Schema Support Feature

Name Supported Defined By
Simple ✓ OAS2,OAS3
Composite ✓ OAS2,OAS3
Polymorphism ✗ OAS2,OAS3
Union ✗ OAS3
allOf ✗ OAS2,OAS3
anyOf ✗ OAS3
oneOf ✗ OAS3
not ✗ OAS3

Security Feature

Name Supported Defined 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

Name Supported Defined By
JSON ✓ OAS2,OAS3
XML ✗ OAS2,OAS3
PROTOBUF ✗ ToolingExtension
Custom ✗ OAS2,OAS3