Skip to content

fix(starter): bundle springdoc — Swagger UI from the starter alone (0.2.1)#50

Merged
jlc488 merged 1 commit into
mainfrom
fix/openapi-bundled-in-starter
Jun 1, 2026
Merged

fix(starter): bundle springdoc — Swagger UI from the starter alone (0.2.1)#50
jlc488 merged 1 commit into
mainfrom
fix/openapi-bundled-in-starter

Conversation

@jlc488
Copy link
Copy Markdown
Contributor

@jlc488 jlc488 commented Jun 1, 2026

What / 무엇

Makes Swagger UI come up from the starter alone — bundle springdoc in the starter so the kit's "add the starter, nothing else" promise covers the API docs too. Ships as 0.2.1.

Swagger UI가 스타터만으로 뜨도록 — springdoc을 스타터에 포함해 "스타터만 추가하면 다 됨" 약속을 API 문서까지 확장. 0.2.1로 배포.

Why / 왜

0.2.0 shipped springdoc as compileOnly, so OpenApiAutoConfiguration only activated if the consumer added springdoc themselves — Swagger UI did not appear from the starter alone. That contradicts the kit's whole premise.

0.2.0은 springdoc을 compileOnly로 배포 → 소비자가 직접 추가해야만 Swagger UI가 떴음. 킷 철학과 어긋남.

How / 어떻게

  • starter — adds api("org.springdoc:springdoc-openapi-starter-webmvc-ui"), so it reaches the consumer's classpath transitively; @ConditionalOnClass(GroupedOpenApi) trips and /swagger-ui + /v3/api-docs serve out of the box.
  • autoconfigure — keeps its compileOnly springdoc + @ConditionalOnClass, so it still compiles/stays dormant without springdoc; the starter guarantees presence.
  • sample-appremoves its own springdoc dependency, so the OpenAPI tests now prove Swagger works from the starter's transitive springdoc alone (the real "starter only" path).
  • opt-out (documented): devslab.kit.openapi.enabled=false (keep jar, disable surface) or exclude the org.springdoc dependency (drop the jar) — Gradle + Maven snippets in the config reference.

Verification / 검증

Full ./gradlew clean build green — 44 tests, 0 failures, with no springdoc declared in sample-app: OpenApiEndpointTests 3/3 (/v3/api-docs 200+valid JSON, admin group, /swagger-ui 200) + OpenApiDisabledTests 1/1. mkdocs --strict clean.

Docs / 문서

README(.ko) Features + Config, docs/reference/configuration(.ko) reworded with exclude snippets, CHANGELOG(.ko) [0.2.1], install coordinates → 0.2.1.

Merge → tag v0.2.1 → Maven Central. (0.2.0 is already published; this is the patch that actually delivers auto-Swagger.)

…r alone (0.2.1)

0.2.0 shipped springdoc as compileOnly, so OpenApiAutoConfiguration only activated if
the consumer added springdoc themselves — Swagger UI did NOT appear from the starter
alone. That contradicts the kit's "add the starter, nothing else" promise. Fix: the
starter now depends on springdoc-openapi-starter-webmvc-ui via api(), so it reaches the
consumer's classpath transitively, @ConditionalOnClass(GroupedOpenApi) trips, and
/swagger-ui + /v3/api-docs serve out of the box with the admin API grouped.

Opt-out, both documented in the configuration reference:
  1. devslab.kit.openapi.enabled=false — keep the jar, disable the surface (production).
  2. exclude the org.springdoc dependency from the starter — drop the jar entirely.

- devslab-kit-spring-boot-starter: add api("org.springdoc:springdoc-openapi-starter-webmvc-ui").
  (autoconfigure keeps its compileOnly springdoc + @ConditionalOnClass, so it still
  compiles and stays dormant without springdoc; the starter is what guarantees presence.)
- sample-app: REMOVE its own springdoc dependency — the OpenApi*Tests now prove Swagger
  works from the starter's transitive springdoc alone (the real "starter only" path).
- README(.ko), docs/reference/configuration(.ko): reword from "add springdoc to opt in"
  to "bundled in the starter; disable via property or exclude the jar", with Gradle +
  Maven exclude snippets.
- CHANGELOG(.ko): [0.2.1] entry. README + installation install coordinates bumped to 0.2.1.

Verified: full `./gradlew clean build` green — 44 tests, 0 failures (OpenApiEndpointTests
3/3 + OpenApiDisabledTests 1/1 with NO springdoc declared in sample-app); mkdocs --strict
clean.
@jlc488 jlc488 merged commit 1f0c7ba into main Jun 1, 2026
2 checks passed
@jlc488 jlc488 deleted the fix/openapi-bundled-in-starter branch June 1, 2026 15:46
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant