Daftar Isi

• Instalasi
• Penggunaan
  • defineAPI() / new API()
  • API.defineEndpoint()
  • API.generateSpec()
• Komponen SwaggerUI
• Contoh

Instalasi

Instal paket dari npm registry:

npm install @deboxsoft/sveltekit-openapi
yarn add @deboxsoft/sveltekit-openapi
pnpm add @deboxsoft/sveltekit-openapi

Penggunaan

defineAPI() / new API()

Gunakan defineAPI atau new API untuk membuat objek API yang menjadi titik pusat pendaftaran endpoint.

const myAPI = defineAPI({
  info: {
    title: "My API",
    description: "Deskripsi My API",
    version: "0.0.1"
  },
  servers: [{ url: "http://localhost:5173" }]
});

API.defineEndpoint()

API.defineEndpoint() digunakan untuk mendefinisikan endpoint. Fungsi ini mengembalikan handler yang kompatibel dengan SvelteKit. Parameter, path, dan body yang Anda definisikan dengan Zod akan divalidasi otomatis.

Contoh singkat (TypeScript):

export const POST = myAPI.defineEndpoint(
  {
    operationId: "createUser",
    summary: "Buat user baru",
    parameters: {
      query: z.object({ my_query_param: z.string().optional() }),
      path: z.object({ my_path_param: z.string().optional() })
    },
    requestBody: z.object({ name: z.string().min(3), age: z.number() }),
    responses: {
      201: {
        content: z.object({
          user: z.object({ id: z.string(), name: z.string(), age: z.number() })
        })
      }
    }
  },
  ({ params, json }) => {
    // params memiliki tipe berdasarkan skema
    return json(201, { user: { id: "123", ...params.body } });
  }
);

Beberapa catatan:

• params akan berisi query, path, dan body sesuai skema yang didefinisikan.
• Fungsi json yang disediakan akan memvalidasi respons terhadap skema yang Anda deklarasikan.

API.generateSpec()

Untuk menyajikan spesifikasi OpenAPI yang dibuat otomatis, panggil generateSpec() dari objek API dan kembalikan sebagai JSON di route SvelteKit.

// `src/routes/api/openapi.json/+server.ts`
import { json, type RequestHandler } from "@sveltejs/kit";
import { myAPI } from "$lib/server/api";

export const GET: RequestHandler = async () => {
  const myAPISpec = await myAPI.generateSpec();
  return json(myAPISpec);
};

Komponen SwaggerUI

Paket ini menyertakan pembungkus SwaggerUI untuk menampilkan dokumentasi secara langsung.

<script lang="ts">
  import { SwaggerUI } from "@deboxsoft/sveltekit-openapi/ui";
</script>

<SwaggerUI url="/api/openapi.json" />

Contoh

• Contoh aplikasi todo tersedia di folder examples/todos-api.

Terima kasih telah menggunakan SvelteKit-OpenAPI. Jika Anda ingin berkontribusi, silakan buat pull request di repository.