From 4ad293dd3b949295caec7957bec2f082e16ce21d Mon Sep 17 00:00:00 2001
From: Ludy <Ludy87@users.noreply.github.com>
Date: Mon, 14 Jul 2025 13:02:13 +0200
Subject: [PATCH] ci: fix Swagger docs generation by targeting stirling-pdf
 module (#3935)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

# Description of Changes

**What was changed**

- Updated the GitHub Actions workflow (`.github/workflows/swagger.yml`)
to invoke the `:stirling-pdf:generateOpenApiDocs` task instead of the
root `generateOpenApiDocs`. Refactored `build.gradle` to apply the
`org.springdoc.openapi-gradle-plugin` exclusively to the `stirling-pdf`
subproject, configured its `openApi` extension, and introduced new
Gradle tasks—`copySwaggerDoc` and `cleanSwaggerInBuild`—to manage the
generated `SwaggerDoc.json` file correctly.

**Why the change was made**

- The previous configuration failed to generate OpenAPI documentation
for the `stirling-pdf` module. These changes ensure that Swagger
documentation is produced from the correct module, uploaded to
SwaggerHub as intended, and that temporary artifacts are cleaned up to
maintain a tidy build directory.


try #3932

---

## Checklist

### General

- [x] I have read the [Contribution
Guidelines](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/CONTRIBUTING.md)
- [x] I have read the [Stirling-PDF Developer
Guide](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/devGuide/DeveloperGuide.md)
(if applicable)
- [ ] I have read the [How to add new languages to
Stirling-PDF](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/devGuide/HowToAddNewLanguage.md)
(if applicable)
- [ ] I have performed a self-review of my own code
- [x] My changes generate no new warnings

### Documentation

- [ ] I have updated relevant docs on [Stirling-PDF's doc
repo](https://github.com/Stirling-Tools/Stirling-Tools.github.io/blob/main/docs/)
(if functionality has heavily changed)
- [ ] I have read the section [Add New Translation
Tags](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/devGuide/HowToAddNewLanguage.md#add-new-translation-tags)
(for new translation tags only)

### UI Changes (if applicable)

- [ ] Screenshots or videos demonstrating the UI changes are attached
(e.g., as comments or direct attachments in the PR)

### Testing (if applicable)

- [ ] I have tested my changes locally. Refer to the [Testing
Guide](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/devGuide/DeveloperGuide.md#6-testing)
for more details.
---
 .github/workflows/swagger.yml |  2 +-
 build.gradle                  | 48 +++++++++++++++++++++++++++--------
 2 files changed, 39 insertions(+), 11 deletions(-)

diff --git a/.github/workflows/swagger.yml b/.github/workflows/swagger.yml
index d717d5563..463736b65 100644
--- a/.github/workflows/swagger.yml
+++ b/.github/workflows/swagger.yml
@@ -29,7 +29,7 @@ jobs:
       - uses: gradle/actions/setup-gradle@ac638b010cf58a27ee6c972d7336334ccaf61c96 # v4.4.1
 
       - name: Generate Swagger documentation
-        run: ./gradlew generateOpenApiDocs
+        run: ./gradlew :stirling-pdf:generateOpenApiDocs
 
       - name: Upload Swagger Documentation to SwaggerHub
         run: ./gradlew swaggerhubUpload
diff --git a/build.gradle b/build.gradle
index 54d702673..84f2c1cb3 100644
--- a/build.gradle
+++ b/build.gradle
@@ -161,6 +161,44 @@ subprojects {
 	tasks.named("processResources") {
 	  dependsOn(rootProject.tasks.writeVersion)
 	}
+
+    if (name == 'stirling-pdf') {
+        apply plugin: 'org.springdoc.openapi-gradle-plugin'
+
+        openApi {
+            apiDocsUrl = "http://localhost:8080/v1/api-docs"
+            outputDir = file("$projectDir")
+            outputFileName = "SwaggerDoc.json"
+            waitTimeInSeconds = 60 // Increase the wait time to 60 seconds
+        }
+
+        tasks.named("forkedSpringBootRun") {
+            dependsOn(":common:jar")
+            dependsOn(":proprietary:jar")
+        }
+
+        tasks.register("copySwaggerDoc", Copy) {
+            doNotTrackState("Writes SwaggerDoc.json to project root")
+            from(layout.projectDirectory.file("SwaggerDoc.json"))
+            into(rootProject.projectDir)
+            dependsOn("generateOpenApiDocs")
+        }
+
+        tasks.register("cleanSwaggerInBuild", Delete) {
+            doNotTrackState("Cleans up SwaggerDoc.json in build directory")
+            delete(layout.projectDirectory.file("SwaggerDoc.json"))
+            dependsOn("copySwaggerDoc")
+        }
+
+        tasks.named("copySwaggerDoc") {
+            finalizedBy("cleanSwaggerInBuild")
+        }
+
+        tasks.named("generateOpenApiDocs") {
+            finalizedBy("copySwaggerDoc")
+            doNotTrackState("OpenAPI plugin writes outside build directory")
+        }
+    }
 }
 
 tasks.withType(JavaCompile).configureEach {
@@ -205,13 +243,6 @@ sourceSets {
     }
 }
 
-openApi {
-    apiDocsUrl = "http://localhost:8080/v1/api-docs"
-    outputDir = file("$projectDir")
-    outputFileName = "SwaggerDoc.json"
-    waitTimeInSeconds = 60 // Increase the wait time to 60 seconds
-}
-
 // Configure the forked spring boot run task to properly delegate to the stirling-pdf module
 tasks.named('forkedSpringBootRun') {
     dependsOn ':stirling-pdf:bootRun'
@@ -566,9 +597,6 @@ tasks.register('printMacVersion') {
     }
 }
 
-tasks.named('generateOpenApiDocs') {
-    doNotTrackState("Tracking state is not supported for this task")
-}
 tasks.named('bootRun') {
     group = 'application'
     description = 'Delegates to :stirling-pdf:bootRun'