Skip to content
agent-cms
참고 / OpenAPI와 다른 서버

참고 / openapi

OpenAPI와 다른 서버

REST API를 OpenAPI 3.1 문서로, 컬렉션마다 타입이 있는 스키마와 함께. 핸들러를 Express, Fastify, Hono 등에 붙이는 법.

수정 2026년 11월 21일편집 docs seed버전 1
이 페이지

note

0.13.0부터.

문서#

sh
curl https://app.example.com/api/cms/openapi.json
npx @mainsoft/agent-cms openapi > openapi.json     # 내 키가 읽을 수 있는 것

이 설치의 지금 설정을 그대로 설명합니다.

  • REST API의 모든 경로와 그 매개변수, 본문, 응답.
  • 읽을 수 있는 컬렉션마다 자기 경로(/collections/posts, /collections/posts/{slug})와 스키마(PostsDoc, PostsInput)가 컬렉션의 필드로 만들어집니다. 그래서 생성한 클라이언트가 실제 타입을 갖습니다. 카테고리는 enum입니다.
  • 꺼져 있는 부분(미디어, cron, 미리보기 링크)은 빠집니다.
  • 로그인하지 않은 사람은 공개 컬렉션만, 키나 세션은 읽을 수 있는 것만 받습니다.

패키지의 테스트가 문서에 적힌 모든 경로를 실제 핸들러에 보내 보고, 어느 쪽으로든 둘이 다르면 실패합니다.

npx openapi-typescript https://app.example.com/api/cms/openapi.json -o cms.d.ts

코드에서는 openApiDocument(cms, { basePath, origin, actor })와 경로 목록 API_ROUTES.

다른 서버#

핸들러는 웹 Request를 받아 웹 Response를 돌려줍니다. 이미 그 둘을 쓰는 프레임워크는 더 필요한 것이 없습니다.

ts
// Hono
app.all("/api/cms/*", (c) => handler(c.req.raw));

// SvelteKit: src/routes/api/cms/[...path]/+server.ts
export const GET = ({ request }) => handler(request);
export const POST = GET, PATCH = GET, PUT = GET, DELETE = GET;

// Bun, Deno
Bun.serve({ fetch: handler });

Node의 (req, res)를 쓰는 서버에는:

ts
import { toNodeHandler } from "@mainsoft/agent-cms/adapters/node";

const handler = createCmsHandler({ cms, resolveUser, basePath: "/api/cms" });

app.use("/api/cms", toNodeHandler(handler));                 // Express
http.createServer(toNodeHandler(handler)).listen(3000);      // node:http

toNodeHandler(handler, { origin, maxBodyBytes }): origin은 서버가 Host와 X-Forwarded-Proto로 알 수 없을 때 사람들이 여는 주소입니다. maxBodyBytes(기본 8MB)를 넘는 본문은 413 body_too_large로 답합니다. express.json() 같은 본문 파서 뒤에서도 동작합니다. toWebRequest(req)는 resolveUser 코드에 다른 곳과 같은 Request를 줍니다.

어드민 화면은 React 컴포넌트이고 API하고만 이야기하므로 어떤 React 앱에서든 돕니다. 다른 언어에서는 위 문서로 클라이언트를 생성하세요.