feat(autoconfigure): auto-configure OpenAPI / Swagger UI for the admin API#48
Merged
Conversation
…n API Add the kit's documented promise to the API-docs surface too: drop springdoc on the classpath and /swagger-ui + /v3/api-docs come up with no wiring, the admin API grouped, and a single property turns it off. - OpenApiAutoConfiguration: @ConditionalOnClass(GroupedOpenApi) so it's dormant until the consumer adds springdoc (declared compileOnly here), @ConditionalOnWebApplication(SERVLET), and @ConditionalOnProperty(devslab.kit.openapi.enabled, matchIfMissing=true) so `devslab.kit.openapi.enabled=false` disables it without removing the dependency (typical in production). Contributes a GroupedOpenApi pinned to /admin/api/v1/** and a default OpenAPI document (title/version); both @ConditionalOnMissingBean so a consumer can override. - DevslabKitProperties: new OpenApi block (enabled / admin-group / title / version). - gradle.properties: SPRINGDOC_VERSION=3.0.3 — the Spring Boot 4 / Spring Framework 7 line (2.8.x targets Spring Boot 3; the Spring Boot BOM does not manage springdoc). Consumed compileOnly by autoconfigure. - sample-app: add springdoc-openapi-starter-webmvc-ui (a consumer opting in) so the end-to-end path is exercised. Verified by sample-app integration tests over the real HTTP stack — this is what proves the springdoc-3.0.x-on-Jackson-3 concern is a non-issue for our setup: - OpenApiEndpointTests (3): /v3/api-docs returns 200 + valid JSON (real serialization), the admin group /v3/api-docs/admin lists /admin/api/v1, and /swagger-ui/index.html is 200 (not blocked — the admin security chain only matches /admin/api/v1/**). - OpenApiDisabledTests (1): enabled=false removes the admin group. Docs: README(.ko) Features + Configuration tables, docs/reference/configuration(.ko) new OpenAPI section, CHANGELOG(.ko) Unreleased. Full `./gradlew build` green (44 tests, 0 failures); mkdocs --strict clean.
jlc488
added a commit
that referenced
this pull request
Jun 1, 2026
…es (#49) Prepare the 0.2.0 release (adds OpenAPI / Swagger UI auto-configuration, #48). - CHANGELOG(.ko): promote the Unreleased OpenAPI entry to [0.2.0] — 2026-06-02. - README(.ko): bump the install snippet to 0.2.0. - docs/getting-started/installation(.ko): bump the dependency coordinates to 0.2.0 and refresh the pre-1.0 note (0.1.0 is published now — "build from source to try unreleased changes" rather than "until 0.1.0 is published"). Historical/context mentions of 0.1.0 (the [0.1.0] changelog heading, "publishes from 0.1.0 onward", roadmap) are left as-is. gradle.properties stays at -SNAPSHOT; release.yml injects the tag version via -PVERSION (sibling pattern).
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What / 무엇
Adds OpenAPI / Swagger UI auto-configuration for the admin API — the "add the starter, nothing else" promise extended to API docs. Drop springdoc on the classpath and
/swagger-ui+/v3/api-docscome up with no wiring, the admin API grouped; one property turns it off.관리자 API용 OpenAPI / Swagger UI 자동 구성 추가 — "스타터만 추가" 철학을 API 문서까지. springdoc만 classpath에 있으면 설정 없이
/swagger-ui+/v3/api-docs가 뜨고 관리자 API가 그룹화됨. 프로퍼티 하나로 끔.How / 어떻게
OpenApiAutoConfiguration—@ConditionalOnClass(GroupedOpenApi)(springdoc는compileOnly라 소비자가 추가해야 활성) +@ConditionalOnWebApplication(SERVLET)+@ConditionalOnProperty(devslab.kit.openapi.enabled, matchIfMissing=true)./admin/api/v1/**를 한 그룹으로 묶는GroupedOpenApi와 기본OpenAPI문서(title/version) 제공 — 둘 다@ConditionalOnMissingBean이라 소비자가 재정의 가능.devslab.kit.openapi.enabled=false— 의존성 제거 없이 비활성화 (프로덕션에서 일반적).SPRINGDOC_VERSION=3.0.3— Spring Boot 4 / Spring Framework 7 라인 (2.8.x는 SB3 대상; Spring Boot BOM이 springdoc을 관리하지 않아 직접 핀). v3.0.3 릴리스가 Spring Boot 4.0.5 지원.DevslabKitProperties.OpenApi—enabled/admin-group/title/version.Tests / 테스트 (real HTTP + Testcontainers)
이게 "springdoc 3.0.x ↔ Spring Boot 4 Jackson 3" 우려가 우리 구성에선 문제없음을 증명:
OpenApiEndpointTests(3):/v3/api-docs→ 200 + 유효 JSON(실제 직렬화 성공), 그룹/v3/api-docs/admin이/admin/api/v1노출,/swagger-ui/index.html→ 200 (admin security chain은/admin/api/v1/**만 잡으므로 미차단).OpenApiDisabledTests(1):enabled=false시 admin 그룹 사라짐.Verification / 검증
Local full
./gradlew buildgreen — 44 tests, 0 failures;mkdocs build --strictclean.Docs / 문서
README(.ko) Features + Configuration 표,
docs/reference/configuration(.ko)새 OpenAPI 섹션, CHANGELOG(.ko) Unreleased.