OpenAPI 명세

Onttle REST API는 OpenAPI 3.0 형식의 명세를 제공합니다. 명세를 사용하면 타입 안전한 클라이언트 코드를 자동 생성하고, Postman이나 Swagger UI로 API를 탐색할 수 있습니다.

---

명세 파일 다운로드

형식	URL
JSON	https://api.onttle.com/workspaces/{{workspaceId}}/projects/{{projectId}}/api/openapi.json

명세는 현재 배포된 API 버전을 기준으로 자동 생성됩니다. JSON URL은 API 엔드포인트 페이지에서 활성화를 한 후 접근이 가능합니다.

YAML 파일은 API 엔드포인트 페이지에서 직접 다운로드가 가능합니다.

---

Bruno로 탐색

Bruno에서 명세를 가져와 API를 탐색할 수 있습니다. JSON URL을 바로 입력하거나, API 엔드포인트 페이지에서 다운로드한 YAML 파일을 가져와 사용할 수 있습니다.

1. Bruno → Import → OpenAPI 선택
2. URL 탭에서 https://api.onttle.com/workspaces/{{workspaceId}}/projects/{{projectId}}/api/openapi.json을 입력하거나, File 탭에서 다운로드한 YAML 파일을 선택
3. Import 클릭하여 Collection 생성
4. 생성된 Collection의 설정에서 API Key를 Bearer Token으로 등록

[이미지 영역] Bruno 에서 Onttle API 탐색 화면

---

Swagger UI로 탐색

브라우저에서 API를 탐색하려면 공식 대시보드의 API 엔드포인트 또는 별도 Swagger UI 인스턴스에 명세 URL을 입력합니다.

https://api.onttle.com/workspaces/{{workspaceId}}/projects/{{projectId}}/api/openapi.json

[이미지 영역] Swagger UI에서 Onttle API 탐색 화면

---

Postman에서 사용하기

1. Postman → Import → URL 탭 선택
2. https://api.onttle.com/workspaces/{{workspaceId}}/projects/{{projectId}}/api/openapi.json 입력
3. Continue → Import 클릭
4. Collection이 생성되면 Authorization 탭에서 Bearer Token으로 API Key를 설정

---

TypeScript 클라이언트 자동 생성

openapi-typescript를 사용해 명세에서 TypeScript 타입을 생성합니다.

npx openapi-typescript https://api.onttle.com/v1/openapi.json -o src/types/onttle-api.d.ts

생성된 타입을 openapi-fetch와 함께 사용하면 완전한 타입 안전 클라이언트를 구성할 수 있습니다.

import createClient from 'openapi-fetch'
import type { paths } from './types/onttle-api'

const client = createClient<paths>({
  baseUrl: 'https://api.onttle.com/v1',
  headers: {
    Authorization: `Bearer ${process.env.ONTTLE_API_KEY}`,
  },
})

// 타입 안전 요청
const { data, error } = await client.GET(
  '/{projectId}/tables/{tableId}/contents',
  {
    params: {
      path: { projectId: 'proj_01hxk2', tableId: 'tbl_01hxk2' },
      query: { status: 'PUBLISHED' },
    },
  },
)

---

SDK에서의 OpenAPI 활용

@openapitools/openapi-generator-cli를 사용하면 JavaScript, Python, Go 등 다양한 언어의 SDK를 생성할 수 있습니다.

npx @openapitools/openapi-generator-cli generate \
  -i https://api.onttle.com/v1/openapi.json \
  -g typescript-fetch \
  -o ./sdk/onttle

---

명세 변경 알림

API 명세 변경은 변경 이력에서 확인할 수 있습니다. 호환성을 깨는 변경이 포함된 경우 별도 마이그레이션 가이드가 함께 제공됩니다.

---

다음 단계

• TypeScript SDK — Onttle TypeScript SDK 사용 방법을 알아봅니다.
• 엔드포인트 명세 — 리소스별 엔드포인트 목록을 확인합니다.