Download, clone or copy OpenAPI contract to project and generate REST interfaces. The plugin is preferred for Spring projects.
Add plugin with clause:
build.gradle.kts
plugins {
id("com.miquido.contractor-plugin") version "1.1.4"
}
settings.gradle.kts
pluginManagement {
repositories {
mavenCentral()
gradlePluginPortal()
// below is optional, only when mavenCentral is not updated yet
maven {
setUrl("https://s01.oss.sonatype.org/content/repositories/releases")
}
}
}
build.gradle
plugins {
id 'com.miquido.contractor-plugin' version '1.1.4'
}
settings.gradle
pluginManagement {
repositories {
mavenCentral()
gradlePluginPortal()
// below is optional, only when mavenCentral is not updated yet
maven {
url = "https://s01.oss.sonatype.org/content/repositories/releases"
}
}
}
Plugin will automatically generate Kotlin/Java interfaces based on configuration.
Plugin needs additional configuration to generate classes.
Example:
import com.miquido.plugin.contractor.strategy.configuration.BaseStrategyConfiguration
import com.miquido.plugin.contractor.strategy.LocalConfigurationAcquireStrategy
import com.miquido.plugin.contractor.strategy.GitlabAccessTokenAcquireStrategy
import com.miquido.plugin.contractor.strategy.GitCloneAcquireStrategy
import com.miquido.plugin.contractor.strategy.FallbackAcquireStrategy
...
configure<ContractorConfiguration> {
contracts = listOf(
GitlabAccessTokenAcquireStrategy(
BaseStrategyConfiguration(
apiGenerationTargetPackagePath = "org.example",
mainSpecificationFilePath = "bank/clients/v1/spec.yaml",
additionalSpecificationFilePaths = mapOf(
"bank/common/v1" to listOf("common.yaml"),
"bank/api/v1" to listOf("firstSpec.yaml", "secondSpec.yaml")
)
),
GitlabAccessTokenAcquireStrategy.Configuration(
projectId = "123456",
accessToken = System.getenv("GITLAB_ACCESS_TOKEN"),
baseUrl = "https://gitlab.com",
branch = "main"
)
),
LocalConfigurationAcquireStrategy(
BaseStrategyConfiguration(
apiGenerationTargetPackagePath = "org.example",
mainSpecificationFilePath = "bank/clients/v1/spec.yaml",
additionalSpecificationFilePaths = mapOf(
"bank/common/v1" to listOf("common.yaml"),
"bank/api/v1" to listOf("firstSpec.yaml", "secondSpec.yaml")
)
),
LocalConfigurationAcquireStrategy.Configuration(
relativePath = ".../example-project"
)
),
GitCloneAcquireStrategy(
BaseStrategyConfiguration(
apiGenerationTargetPackagePath = "org.example",
mainSpecificationFilePath = "bank/clients/v1/spec.yaml",
additionalSpecificationFilePaths = mapOf(
"bank/common/v1" to listOf("common.yaml"),
"bank/api/v1" to listOf("firstSpec.yaml", "secondSpec.yaml")
)
),
GitCloneAcquireStrategy.Configuration(
gitCloneUrl = "git@gitlab.com:company/example/example-project.git",
repositoryName = "example-project",
branchName = "main"
)
),
FallbackAcquireStrategy(
BaseStrategyConfiguration(
apiGenerationTargetPackagePath = "org.example",
mainSpecificationFilePath = "bank/clients/v1/spec.yaml",
additionalSpecificationFilePaths = mapOf(
"bank/common/v1" to listOf("common.yaml"),
"bank/api/v1" to listOf("firstSpec.yaml", "secondSpec.yaml")
)
),
FallbackAcquireStrategy.Configuration(
strategyConfigurations = listOf(
GitlabAccessTokenAcquireStrategy.Configuration(...),
LocalConfigurationAcquireStrategy.Configuration(...),
GitCloneAcquireStrategy.Configuration(...)
)
)
)
)
generatorName = "spring"
importMappings = listOf(
"StreamingResponseBody": "org.springframework.web.servlet.mvc.method.annotation.StreamingResponseBody",
"BigInteger": "java.math.BigInteger"
)
typeMappings = listOf(
"array+binary": "StreamingResponseBody",
"string+bigint": "BigInteger"
)
configOptions = mapOf(
'useTags' to 'true',
'openApiNullable' to 'false',
'generateConstructorWithAllArgs' to 'false',
'generatedConstructorWithRequiredArgs' to 'false',
'bigDecimalAsString' to 'true'
)
}
import com.miquido.plugin.contractor.strategy.configuration.BaseStrategyConfiguration
import com.miquido.plugin.contractor.strategy.LocalConfigurationAcquireStrategy
import com.miquido.plugin.contractor.strategy.GitlabAccessTokenAcquireStrategy
import com.miquido.plugin.contractor.strategy.GitCloneAcquireStrategy
import com.miquido.plugin.contractor.strategy.FallbackAcquireStrategy
...
contractorPluginConfiguration {
contracts = [
new GitlabAccessTokenAcquireStrategy(
new BaseStrategyConfiguration(
"org.example", // apiGenerationTargetPackagePath
"bank/clients/v1/spec.yaml", // mainSpecificationFilePath
[
"bank/common/v1": ["common.yaml"],
"bank/api/v1": ["firstSpec.yaml", "secondSpec.yaml"],
]
),
new GitlabAccessTokenAcquireStrategy.Configuration(
"123456", // projectId
System.getenv("GITLAB_ACCESS_TOKEN"), // accessToken
"https://gitlab.com", // baseUrl
"main" // branch
)
),
new LocalConfigurationAcquireStrategy(
new BaseStrategyConfiguration(
"org.example", // apiGenerationTargetPackagePath
"bank/clients/v1/spec.yaml", // mainSpecificationFilePath
[
"bank/common/v1": ["common.yaml"],
"bank/api/v1": ["firstSpec.yaml", "secondSpec.yaml"],
]
),
new LocalConfigurationAcquireStrategy.Configuration(
".../example-project" // relativePath
)
),
new GitCloneAcquireStrategy(
new BaseStrategyConfiguration(
"org.example", // apiGenerationTargetPackagePath
"bank/clients/v1/spec.yaml", // mainSpecificationFilePath
[
"bank/common/v1": ["common.yaml"],
"bank/api/v1": ["firstSpec.yaml", "secondSpec.yaml"],
]
),
new GitCloneAcquireStrategy.Configuration(
"git@gitlab.com:company/example/example-project.git", // gitCloneUrl
"example-project", // repositoryName
"main" // branchName
)
),
new FallbackAcquireStrategy(
new BaseStrategyConfiguration(
"org.example", // apiGenerationTargetPackagePath
"bank/clients/v1/spec.yaml", // mainSpecificationFilePath
[
"bank/common/v1": ["common.yaml"],
"bank/api/v1": ["firstSpec.yaml", "secondSpec.yaml"],
]
),
new FallbackAcquireStrategy.Configuration(
[ // strategyConfigurations
new GitlabAccessTokenAcquireStrategy.Configuration(...),
new LocalConfigurationAcquireStrategy.Configuration(...),
new GitCloneAcquireStrategy.Configuration(...)
]
)
)
]
generatorName = "spring"
skipValidateSpec = true
importMappings = [
"StreamingResponseBody": "org.springframework.web.servlet.mvc.method.annotation.StreamingResponseBody",
"BigInteger": "java.math.BigInteger"
]
typeMappings = [
"array+binary": "StreamingResponseBody",
"string+bigint": "BigInteger"
]
configOptions = [
useTags: 'true',
openApiNullable: 'false',
generateConstructorWithAllArgs: 'false',
generatedConstructorWithRequiredArgs: 'false',
bigDecimalAsString: 'true'
]
}
| Parameter | Description |
|---|---|
| contracts | Specified by Strategy classes. Every defined contract creates specification classes. |
| skipValidateSpec | Whether or not to skip validating the input spec prior to generation. By default, invalid specifications will result in an error. For more see https://github.com/OpenAPITools/openapi-generator/blob/master/modules/openapi-generator-maven-plugin/README.md |
| generatorName | Generator name for OpenAPI plugin configuration. Available generators: https://openapi-generator.tech/docs/generators/#server-generators |
| importMappings | Custom types mapping configuration. For more, see https://openapi-generator.tech/docs/usage/#type-mappings-and-import-mappings |
| typeMappings | Custom types mapping configuration. For more, see https://openapi-generator.tech/docs/usage/#type-mappings-and-import-mappings |
| configOptions | Overrides default OpenAPI plugin configuration. Both can be found at https://openapi-generator.tech/docs/generators/kotlin/ and https://openapi-generator.tech/docs/generators/kotlin-spring/. |
| Class name | Description |
|---|---|
| LocalConfigurationAcquireStrategy | Used for retrieving API contract files from SOURCE PROJECT placed in local directory |
| GitlabAccessTokenAcquireStrategy | Used for retrieving API contract files from SOURCE PROJECT placed in gitlab repository, by downloading it using an access token |
| GitCloneAcquireStrategy | Used for retrieving API contract files from SOURCE PROJECT placed in any git repository, by cloning it using local git settings |
| FallbackAcquireStrategy | Used for retrieving API contract files from SOURCE PROJECT using the first encountered strategy from the given list that is capable of doing so |
| Class name | Description |
|---|---|
| BaseStrategyConfiguration | Main configuration that is used in every strategy |
| LocalConfigurationAcquireStrategy.Configuration | Additional configuration that is used by LocalConfigurationAcquireStrategy |
| GitlabAccessTokenAcquireStrategy.Configuration | Additional configuration that is used by GitlabAccessTokenAcquireStrategy |
| GitCloneAcquireStrategy.Configuration | Additional configuration that is used by GitCloneAcquireStrategy |
| FallbackAcquireStrategy.Configuration | Additional configuration that is used by FallbackAcquireStrategy |
| Attribute | Description |
|---|---|
| directoryList | Directory path list in SOURCE PROJECT where api specification file should be looked |
| fileFullName | Api specification file full name placed in directoryList |
| Attribute | Description |
|---|---|
| directoryList | Directory path list in SOURCE PROJECT where api specification files should be looked |
| fileFullNames | List of api specification file full names placed in directoryList |
| Attribute | Description |
|---|---|
| apiGenerationTargetPackagePath | Base package path list in TARGET PROJECT where generated api should be generated |
| mainSpecificationFilePath | Main API contract file path and name SingleFile |
| additionalSpecificationFilePaths | OPTIONAL FIELD. List of additional API contract files names and paths MultipleFiles. It should be ordered relative to the references($ref) inside these files. If not introduced, plugin will try to detect and acquire necessary files |
| Attribute | Description |
|---|---|
| baseConfiguration | Base configuration BaseStrategyConfiguration |
| configuration.relativePath | Path of locally stored API contract SOURCE PROJECT |
| Attribute | Description |
|---|---|
| baseConfiguration | Base configuration BaseStrategyConfiguration |
| configuration.projectId | Gitlab project id |
| configuration.accessToken | Gitlab access token |
| configuration.baseUrl | Gitlab base url of SOURCE PROJECT (default: https://gitlab.com) |
| configuration.branch | Branch of the project repository from which the file is to be downloaded |
| Attribute | Description |
|---|---|
| baseConfiguration | Base configuration BaseStrategyConfiguration |
| configuration.gitCloneUrl | Git url for cloning |
| configuration.repositoryName | Name of SOURCE PROJECT repository |
| configuration.branchName | Branch of the project repository from which the file is to be cloned |
| Attribute | Description |
|---|---|
| baseConfiguration | Base configuration BaseStrategyConfiguration |
| configuration.strategyConfigurations | A list of strategies configurations that defines the order of checking which of them can be used to obtain a API contract |
| Attribute | Description |
|---|---|
| SOURCE PROJECT | Project where api specification files are stored |
| TARGET PROJECT | Project where api classes will be generated |
- What do this plugin use to generate API files?
- How can I generate separate API interfaces files in My TARGET PROJECT for each endpoint?
API interfaces files are generated based on tags parameter declared on each path element(if useTags configuration is enabled). If two or more path have the same tag, then all of them will be placed in the same file.
- In generated API methods names include name of their API, what can I do to remove it? What can I do, to declare my own names of methods?
API methods names can be declared with parameter operationId parameter declared on each path element.