Skip to content

ApiLens v0.3.2

Choose a tag to compare

View all tags
@github-actions github-actions released this 10 Jul 09:33
v0.3.2
80c6933

ApiLens v0.3.2 — API 문서 자동화 (Swagger UI) | Automated API Docs (Swagger UI)

손으로 쓰던 마크다운 API 문서가 코드와 어긋나던 문제를, 컨트롤러에서 스펙을 자동으로
만들어 단일 jar 에 담는 방식으로 근본 해소했습니다. server 를 띄운 뒤 /swagger-ui
(인터랙티브 문서) 또는 /v3/api-docs (OpenAPI JSON) 를 열면 최신 요청·응답 스키마와
상태 코드를 그대로 확인하고 시험 호출할 수 있습니다. server 와 UI 의 버전 라벨만
바뀌고 agent·common 모듈은 변경 없음 — v0.1~v0.3.1 agent 그대로 호환됩니다.

We fixed the hand-written Markdown API docs — which kept drifting from the code — by
generating the spec from the controllers and embedding interactive docs in the single jar.
Start the server and open /swagger-ui (interactive) or /v3/api-docs (OpenAPI JSON) to
inspect and try the current request/response schemas and status codes. Only the server
and UI version labels changed; the agent and common modules are unchanged (fully
compatible with v0.1–v0.3.1 agents).

새로운 기능 | What's new

  • API 문서 자동화 (OpenAPI / Swagger UI) — springdoc-openapi 로 컨트롤러에서 스펙을 자동 생성하고 인터랙티브 문서를 단일 jar 에 임베드했습니다. 손으로 문서를 갱신하지 않아도 전체 엔드포인트가 코드와 항상 일치합니다. server 전용 의존성이라 agent 는 무관 (재빌드 불필요).
  • 문서 경로는 인증 없이 열립니다 — API Key 를 설정한 기동 상태에서도 /swagger-ui · /v3/api-docs 는 토큰 없이 접근할 수 있습니다 (의도된 면제). 기존 /v1/** 관리·조회 API 의 보호는 그대로 유지됩니다. 문서 경로를 위한 신규 필터·인터셉터는 추가하지 않았습니다.
  • 문서 버전이 빌드 버전을 자동 추종 — OpenAPI info.version 을 손으로 적지 않고 빌드 버전에서 주입해, 버전을 올릴 때 문서 버전이 어긋나는 문제를 원천 차단했습니다.

업그레이드 | Upgrade

  • collector(server) jar 만 0.3.2 로 교체하고 재기동하면 됩니다. agent jar 재배포 불필요 (agent 무변경).
  • 스키마 변경 0 — 0.3.1 DB 와 그대로 호환되고, 0.3.1 로 롤백해도 데이터 영향이 없습니다.

Replace only the collector (server) jar with 0.3.2 and restart. No agent redeploy needed
(agent unchanged). No schema change — fully compatible with 0.3.1 databases, and rolling
back to 0.3.1 has no data impact.

주의 | Notes

  • /swagger-ui · /v3/api-docs 는 인증 없이 열립니다. 신뢰망 안에서 운영자가 단독으로 쓰는 전제라 문서 경로는 면제로 두었습니다. server 를 인터넷에 직접 노출하는 배포라면, 앞단 리버스 프록시(nginx 등)에서 이 두 경로를 인증/차단하는 것을 권장합니다.
  • 필드 단위 요청/응답 계약의 단일 진실 출처는 이제 자동 스펙(/swagger-ui)입니다. docs/api.md 에는 자동 스펙이 담기 어려운 운영 서사(유지보수 중 503, 마스킹 적용 시점, 인증 헤더 전제 등)만 남겼습니다.

/swagger-ui and /v3/api-docs are exposed without authentication (intended, for a
single trusted-network operator). If you expose the server directly to the internet, put a
reverse proxy (e.g. nginx) in front and authenticate or block those two paths.

전체 변경 내역은 CHANGELOG 를 참고하세요. | See the CHANGELOG for full details.

Assets 4
Loading