OpenAPI 스펙
실행 중인 서버가 직접 제공하는 라이브 스펙입니다.
Hono 서버는 라우트가 쓰는 같은 Zod 스키마에서 생성한 OpenAPI 3.1 스펙을 직접 제공합니다. 동기화해야 할 별도 스펙 파일은 없습니다. 스펙, SDK 타입, 라우트 핸들러가 모두 같은 한 소스에서 파생됩니다.
어디서 찾는지
서버가 실행 중일 때:
| URL | 포맷 |
|---|---|
http://localhost:3099/openapi.json | 원시 JSON (기계 판독 가능) |
http://localhost:3099/docs | Swagger UI (인터랙티브) |
http://localhost:3099/spec | 평문 덤프 |
3099는 startSnaServer({ port })가 반환한 포트로 바꿔서 사용하세요.
인증 계약
런타임 스펙은 components.securitySchemes.bearerAuth를 포함하고 문서 레벨에
security: [{ bearerAuth: [] }]를 설정합니다. GET /health만 공개 operation이며
security: []로 표시됩니다. 보호된 operation에는 표준 error envelope을 쓰는
공통 401과 403 응답이 포함됩니다.
/openapi.json, /docs, /spec에 직접 접근할 때도 다른 런타임 라우트와
같은 인증 middleware를 거칩니다. 정적 문서 생성은 docs build script 안에서만
unsafeDisableAuth를 사용하므로 라이브 secret 없이 published reference를
생성할 수 있습니다.
유스케이스
- 다른 언어 클라이언트 생성.
/openapi.json에 원하는 OpenAPI 코드젠을 연결할 수 있습니다. 스키마가 strict(Zod 파생)이므로 출력은 타입 안전합니다. - 인터랙티브 탐색. Swagger UI에서 인증과 body 편집기를 사용해 브라우저에서 모든 라우트를 호출할 수 있습니다.
- CI에서 계약 고정. 스펙을 디스크에 스냅샷하고 빌드마다 diff를 확인합니다. 의도치 않은 공개 표면 변경이 diff로 드러납니다.
안정성
라우트는 SNA 워크스페이스 전반에서 semver를 따릅니다. 하위 호환 안 되는 라우트 변경은 메이저 버전으로 출시됩니다. OpenAPI 태그는 라우트를 표면별(Sessions, Agent, Permissions, Chat)로 묶으므로 생성 클라이언트도 자연스러운 그룹을 갖습니다.
라우트와 한 줄 설명 전체 목록은 HTTP 라우트에 있습니다. 각 라우트가 emit할 수 있는 이벤트 타입은 이벤트를 보세요.