Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Support for custom bootRun tasks & Drop Support for Spring Boot 2.x #159

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
+389 −249
Open

Support for custom bootRun tasks & Drop Support for Spring Boot 2.x #159

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
69 changes: 42 additions & 27 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,10 +6,11 @@ Gradle plugin for springdoc-openapi.

This plugin allows you to generate an OpenAPI 3 specification for a Spring Boot
application from a Gradle build.

Compatibility Notes
-------------------

The plugin is built on Gradle version 7.0.
The plugin is built on Gradle version 8.12.1 and Java 17.

Dependencies
------------
Expand All @@ -25,17 +26,17 @@ Gradle Groovy DSL

```groovy
plugins {
id "org.springframework.boot" version "2.7.0"
id "org.springdoc.openapi-gradle-plugin" version "1.9.0"
id "org.springframework.boot" version "3.4.2"
id "org.springdoc.openapi-gradle-plugin" version "2.0.0"
}
```

Gradle Kotlin DSL

```groovy
```kotlin
plugins {
id("org.springframework.boot") version "2.7.0"
id("org.springdoc.openapi-gradle-plugin") version "1.9.0"
id("org.springframework.boot") version "3.4.2"
id("org.springdoc.openapi-gradle-plugin") version "2.0.0"
}
```

Expand Down Expand Up @@ -80,30 +81,34 @@ openApi {
trustStore.set("keystore/truststore.p12")
trustStorePassword.set("changeit".toCharArray())
groupedApiMappings.set(
["https://localhost:8080/v3/api-docs/groupA" to "swagger-groupA.json",
"https://localhost:8080/v3/api-docs/groupB" to "swagger-groupB.json"]
mapOf(
"https://localhost:8080/v3/api-docs/groupA" to "swagger-groupA.json",
"https://localhost:8080/v3/api-docs/groupB" to "swagger-groupB.json"
)
)
customBootRun {
args.set(["--spring.profiles.active=special"])
args.set(listOf("--spring.profiles.active=special"))
}
requestHeaders = [
"x-forwarded-host": "custom-host",
"x-forwarded-port": "7000"
]
requestHeaders = mapOf(
"x-forwarded-host" to "custom-host",
"x-forwarded-port" to "7000"
)
}
```

| Parameter | Description | Required | Default |
|----------------------|-------------------------------------------------------------------------------------------------------------------------------------|----------|--------------------------------------|
| `apiDocsUrl` | The URL from where the OpenAPI doc can be downloaded. If the url ends with `.yaml`, output will YAML format. | No | http://localhost:8080/v3/api-docs |
| `outputDir` | The output directory for the generated OpenAPI file | No | $buildDir - Your project's build dir |
| `outputFileName` | Specifies the output file name. | No | openapi.json |
| `waitTimeInSeconds` | Time to wait in seconds for your Spring Boot application to start, before we make calls to `apiDocsUrl` to download the OpenAPI doc | No | 30 seconds |
| `trustStore` | Path to a trust store that contains custom trusted certificates. | No | `<None>` |
| `trustStorePassword` | Password to open Trust Store | No | `<None>` |
| `groupedApiMappings` | A map of URLs (from where the OpenAPI docs can be downloaded) to output file names | No | [] |
| `customBootRun` | Any bootRun property that you would normal need to start your spring boot application. | No | (N/A) |
| `requestHeaders` | customize Generated server url, relies on `server.forward-headers-strategy=framework` | No | (N/A) |
| Parameter | Description | Required | Default |
|----------------------------|-------------------------------------------------------------------------------------------------------------------------------------|----------|--------------------------------------|
| `apiDocsUrl` | The URL from where the OpenAPI doc can be downloaded. If the url ends with `.yaml`, output will YAML format. | No | http://localhost:8080/v3/api-docs |
| `outputDir` | The output directory for the generated OpenAPI file | No | $buildDir - Your project's build dir |
| `outputFileName` | Specifies the output file name. | No | openapi.json |
| `waitTimeInSeconds` | Time to wait in seconds for your Spring Boot application to start, before we make calls to `apiDocsUrl` to download the OpenAPI doc | No | 30 seconds |
| `trustStore` | Path to a trust store that contains custom trusted certificates. | No | `<None>` |
| `trustStorePassword` | Password to open Trust Store | No | `<None>` |
| `groupedApiMappings` | A map of URLs (from where the OpenAPI docs can be downloaded) to output file names | No | [] |
| `customBootRun` | Any bootRun property that you would normal need to start your spring boot application. | No | (N/A) |
| `requestHeaders` | customize Generated server url, relies on `server.forward-headers-strategy=framework` | No | (N/A) |
| `bootRunTaskName` | The name of the bootRun task to be used to start the Spring Boot application. | No | bootRun |
| `classNameResolveTaskName` | The name of the task to resolve the main class of the Spring Boot application. | No | resolveMainClassName |

### `customBootRun` properties examples

Expand All @@ -115,15 +120,25 @@ as `args`, `jvmArgs`, `systemProperties` and `workingDir`.
If you don't specify `customBootRun` parameter, this plugin uses the parameter specified
to `bootRun` in Spring Boot Gradle Plugin.

#### Running with Spring Boot Testcontainers Support

AS a convenience, you can use the `useTestBootRun` method to configure this plugin to use the `bootTestRun` task available with the Spring Boot Testcontainers support added in Spring Boot since 3.1.x.

```kotlin
openApi {
useTestBootRun()
}
```

#### Passing static args

This allows for you to be able to just send the static properties when executing Spring
application in `generateOpenApiDocs`.

```
```kotlin
openApi {
customBootRun {
args = ["--spring.profiles.active=special"]
args.set(listOf("--spring.profiles.active=special"))
}
}
```
Expand Down Expand Up @@ -183,7 +198,7 @@ OpenAPI doc.
in `build.gradle.kts`

```
id("org.springdoc.openapi-gradle-plugin") version "1.8.0"
id("org.springdoc.openapi-gradle-plugin") version "2.0.0"
```

3. Add the following to the spring boot apps `settings.gradle`
Expand Down
47 changes: 25 additions & 22 deletions build.gradle.kts
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,15 +1,18 @@
import org.jetbrains.kotlin.gradle.dsl.JvmTarget

plugins {
`java-gradle-plugin`
id("com.gradle.plugin-publish") version "1.2.0"
id("org.sonarqube") version "3.1.1"
kotlin("jvm") version "1.8.20"
alias(libs.plugins.plugin.publish)
alias(libs.plugins.sonarqube)
kotlin("jvm") version libs.versions.kotlin
`kotlin-dsl`
`maven-publish`
id("com.github.ben-manes.versions") version "0.38.0"
id("io.gitlab.arturbosch.detekt") version "1.23.1"
alias(libs.plugins.versions)
alias(libs.plugins.detekt)
}

group = "org.springdoc"
version = "1.9.0"
version = "2.0.0"

sonarqube {
properties {
Expand All @@ -27,6 +30,7 @@ repositories {
name = "Gradle Plugins Maven Repository"
url = uri("https://plugins.gradle.org/m2/")
}
mavenLocal()
}

publishing {
Expand All @@ -40,9 +44,9 @@ publishing {
url = if (version.toString()
.endsWith("SNAPSHOT")
) {
snapshotsRepoUrl
snapshotsRepoUrl
} else {
releasesRepoUrl
releasesRepoUrl
}
credentials {
username = System.getenv("OSSRH_USER")
Expand All @@ -54,19 +58,19 @@ publishing {

dependencies {
implementation(kotlin("reflect"))
implementation("com.google.code.gson:gson:2.8.9")
implementation("org.awaitility:awaitility-kotlin:4.0.3")
implementation("com.github.psxpaul:gradle-execfork-plugin:0.2.0")
implementation("org.springframework.boot:spring-boot-gradle-plugin:2.7.14")
implementation(gradleKotlinDsl())
implementation(libs.klaxon)
implementation(libs.awaitility.kotlin)
implementation(libs.pluginlib.gradle.execfork)
implementation(libs.pluginlib.spring.boot)

testImplementation(gradleTestKit())
testImplementation(platform("org.junit:junit-bom:5.7.1"))
testImplementation(platform(libs.junit.bom))
testImplementation("org.junit.jupiter:junit-jupiter")
testImplementation("com.beust:klaxon:5.5")
testImplementation("com.fasterxml.jackson.module:jackson-module-kotlin:2.15.2")
testImplementation("com.fasterxml.jackson.dataformat:jackson-dataformat-yaml:2.13.2")
testImplementation(libs.jackson.kotlin)
testImplementation(libs.jackson.yaml)

detektPlugins("io.gitlab.arturbosch.detekt:detekt-formatting:1.23.1")
detektPlugins(libs.detekt.formatting)
}

gradlePlugin {
Expand All @@ -83,17 +87,16 @@ gradlePlugin {
}
}

val jvmVersion: JavaLanguageVersion = JavaLanguageVersion.of(8)

java {
toolchain.languageVersion.set(jvmVersion)
toolchain.languageVersion.set(libs.versions.java.map(JavaLanguageVersion::of))
// Recommended by https://docs.gradle.org/current/userguide/building_java_projects.html#sec:java_packaging
withSourcesJar()
}

tasks.withType<org.jetbrains.kotlin.gradle.tasks.KotlinCompile> {
kotlinOptions {
jvmTarget = "1.$jvmVersion"
compilerOptions{
jvmTarget.set(libs.versions.java.map (JvmTarget::fromTarget))
}
}

Expand All @@ -108,5 +111,5 @@ detekt {
parallel = true
}
tasks.withType<io.gitlab.arturbosch.detekt.Detekt>().configureEach {
jvmTarget = "1.$jvmVersion"
jvmTarget = libs.versions.java.get()
}
23 changes: 23 additions & 0 deletions gradle/libs.versions.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,23 @@
[versions]
java = "17"
kotlin = "2.0.21"
spring-boot = "3.4.2"
detekt = "1.23.6"
junit = "5.11.4"
jackson = "2.18.2"

[libraries]
awaitility-kotlin = { group = "org.awaitility", name = "awaitility-kotlin", version = "4.2.2" }
detekt-formatting = { group = "io.gitlab.arturbosch.detekt", name = "detekt-formatting", version.ref = "detekt" }
junit-bom = { group = "org.junit", name = "junit-bom", version.ref = "junit" }
klaxon = { group = "com.beust", name = "klaxon", version = "5.5" }
pluginlib-spring-boot = { group = "org.springframework.boot", name = "spring-boot-gradle-plugin", version.ref = "spring-boot" }
pluginlib-gradle-execfork = { group = "com.github.psxpaul", name = "gradle-execfork-plugin", version = "0.2.2" }
jackson-yaml = { group = "com.fasterxml.jackson.dataformat", name = "jackson-dataformat-yaml", version.ref = "jackson" }
jackson-kotlin = { group = "com.fasterxml.jackson.module", name = "jackson-module-kotlin", version.ref = "jackson" }

[plugins]
detekt = { id = "io.gitlab.arturbosch.detekt", version.ref = "detekt" }
plugin-publish = { id = "com.gradle.plugin-publish", version = "1.3.1" }
sonarqube = { id = "org.sonarqube", version = "6.0.1.5171" }
versions = { id = "com.github.ben-manes.versions", version = "0.52.0" }
Binary file modified gradle/wrapper/gradle-wrapper.jar
View file
Open in desktop
Binary file not shown.
2 changes: 1 addition & 1 deletion gradle/wrapper/gradle-wrapper.properties
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
distributionBase=GRADLE_USER_HOME
distributionPath=wrapper/dists
distributionUrl=https\://services.gradle.org/distributions/gradle-8.2.1-bin.zip
distributionUrl=https\://services.gradle.org/distributions/gradle-8.12.1-bin.zip
networkTimeout=10000
validateDistributionUrl=true
zipStoreBase=GRADLE_USER_HOME
Expand Down
Loading