From 9b636bd73ee3fb405ec14b206db07cd25705a7cd Mon Sep 17 00:00:00 2001
From: Andrew Berezovskyi <andriib@kth.se>
Date: Sat, 4 Jul 2026 23:17:01 +0200
Subject: [PATCH] docs: add swagger migration steps and common issue for lyo
 6.0 migration

---
 docs-new/eclipse_lyo/migration-5x-6x.md | 39 +++++++++++++++++++++++++
 1 file changed, 39 insertions(+)

diff --git a/docs-new/eclipse_lyo/migration-5x-6x.md b/docs-new/eclipse_lyo/migration-5x-6x.md
index 57aa6ac..68934b2 100644
--- a/docs-new/eclipse_lyo/migration-5x-6x.md
+++ b/docs-new/eclipse_lyo/migration-5x-6x.md
@@ -169,6 +169,38 @@ Replace all Java EE dependencies with Jakarta EE equivalents:
 </dependency>
 ```
 
+#### 2.5 Swagger Dependencies (if using Swagger)
+
+If the project integrates Swagger for OpenAPI documentation, the Swagger JAX-RS integration dependencies shall be updated to their Jakarta EE compatible counterparts (using the `-jakarta` artifact ID suffix):
+
+```xml
+<!-- OLD: Swagger dependencies (javax namespace) -->
+<!--
+<dependency>
+    <groupId>io.swagger.core.v3</groupId>
+    <artifactId>swagger-jaxrs2</artifactId>
+    <version>${swagger.version}</version>
+</dependency>
+<dependency>
+    <groupId>io.swagger.core.v3</groupId>
+    <artifactId>swagger-jaxrs2-servlet-initializer-v2</artifactId>
+    <version>${swagger.version}</version>
+</dependency>
+-->
+
+<!-- NEW: Swagger dependencies (jakarta namespace) -->
+<dependency>
+    <groupId>io.swagger.core.v3</groupId>
+    <artifactId>swagger-jaxrs2-jakarta</artifactId>
+    <version>${swagger.version}</version>
+</dependency>
+<dependency>
+    <groupId>io.swagger.core.v3</groupId>
+    <artifactId>swagger-jaxrs2-servlet-initializer-v2-jakarta</artifactId>
+    <version>${swagger.version}</version>
+</dependency>
+```
+
 ### Phase 3: Code Migration
 
 #### 3.1 Package Name Changes
@@ -337,6 +369,13 @@ mvn package
 
 **Solution:** Ensure all `javax.*` imports are changed to `jakarta.*` and dependencies are updated.
 
+**Issue: NoClassDefFoundError for JAX-RS / javax classes during server startup (e.g. HttpHeaders)**
+
+> java.lang.NoClassDefFoundError: javax/ws/rs/core/HttpHeaders
+> at org.glassfish.jersey.server.model.IntrospectionModeller...
+
+**Solution:** Ensure that the Swagger/OpenAPI dependencies are migrated to their Jakarta EE equivalents with the `-jakarta` suffix (e.g., `swagger-jaxrs2-jakarta` and `swagger-jaxrs2-servlet-initializer-v2-jakarta` instead of `swagger-jaxrs2` and `swagger-jaxrs2-servlet-initializer-v2`).
+
 **Issue: Jersey injection problems**
 
 > java.lang.IllegalStateException: ServiceLocator has been shut down