ZappsDocs – Dokumentasi Penggunaan

ZappsDocs adalah UI dokumentasi OpenAPI (Swagger) yang dibuat khusus untuk ekosistem NestJS, dengan fokus pada:

• UI modern dan cepat (Vue 3 + Tailwind)
• Integrasi mudah dengan NestJS (Express maupun Fastify)
• Playground interaktif (coba request langsung dari halaman docs)

Dokumen ini menjelaskan dari instalasi sampai cara penggunaan di aplikasi NestJS.

1. Instalasi

Pastikan package manager yang digunakan adalah pnpm.

pnpm add zappsdocs

ZappsDocs hanya membutuhkan dependency di sisi NestJS pada runtime:

• @nestjs/common, @nestjs/core, dsb. (sudah ada di project NestJS)
• zappsdocs sebagai library UI docs

Catatan: ZappsDocs sudah dibundel sebagai library, jadi kamu tidak perlu meng-install Vue atau Pinia di aplikasi NestJS.

2. Konsep Dasar Integrasi

ZappsDocs bekerja dengan 3 komponen:

1. OpenAPI Document
   Biasanya dihasilkan dari @nestjs/swagger:

   import { SwaggerModule, DocumentBuilder } from '@nestjs/swagger';
   
   const config = new DocumentBuilder()
     .setTitle('User API')
     .setDescription('API untuk user service')
     .setVersion('1.0')
     .build();
   
   const document = SwaggerModule.createDocument(app, config);

2. Middleware/Helper ZappsDocs (server)
   Disediakan oleh zappsdocs/server:

   • zappsDocsFastify(fastify, routePath, document, options?)
   • zappsDocsExpress(routePath, document, options?)

3. UI Client ZappsDocs
   Sudah dibundel dalam library dan akan di-load otomatis ketika route docs diakses.

Arsitektur singkat:

NestJS (Fastify/Express)
  └── ZappsDocs server helper
        ├── Serve HTML + asset JS/CSS
        └── Inject window.__ZAPPS_SPEC__ + window.__ZAPPS_OPTIONS__
              └── ZappsDocs UI (Vue) merender halaman dokumentasi

3. Penggunaan dengan NestJS + Fastify

Contoh integrasi di main.ts dengan FastifyAdapter:

import { NestFactory } from '@nestjs/core';
import { FastifyAdapter, NestFastifyApplication } from '@nestjs/platform-fastify';
import { SwaggerModule, DocumentBuilder } from '@nestjs/swagger';
import { AppModule } from './app.module';
import { zappsDocsFastify } from 'zappsdocs/server';

async function bootstrap() {
  const app = await NestFactory.create<NestFastifyApplication>(
    AppModule,
    new FastifyAdapter(),
  );

  // Swagger/OpenAPI
  const config = new DocumentBuilder()
    .setTitle('User Service API')
    .setDescription('Dokumentasi API user service')
    .setVersion('1.0.0')
    .build();

  const document = SwaggerModule.createDocument(app, config);

  // Integrasi ZappsDocs
  const fastifyInstance = app.getHttpAdapter().getInstance();

  zappsDocsFastify(fastifyInstance, '/zappsdocs', document, {
    title: 'User Service Docs',
    description: 'Dokumentasi API internal',
    version: '1.0.0',
    servers: [
      { url: 'http://localhost:3000', description: 'Local' },
    ],
    auth: {
      type: 'bearer',
    },
    layout: 'modern',        // 'modern' | 'classic'
    theme: 'system',         // 'light' | 'dark' | 'system'
    responseMode: 'tabs',    // 'tabs' | 'cards'
  });

  await app.listen(3000, '0.0.0.0');
}

bootstrap();

Setelah ini:

• Buka http://localhost:3000/zappsdocs untuk melihat UI ZappsDocs.

4. Penggunaan dengan NestJS + Express

Jika kamu memakai NestFactory.create(AppModule) default (Express), gunakan helper Express:

import { NestFactory } from '@nestjs/core';
import { SwaggerModule, DocumentBuilder } from '@nestjs/swagger';
import { AppModule } from './app.module';
import { zappsDocsExpress } from 'zappsdocs/server';

async function bootstrap() {
  const app = await NestFactory.create(AppModule);

  const config = new DocumentBuilder()
    .setTitle('User Service API')
    .setDescription('Dokumentasi API user service')
    .setVersion('1.0.0')
    .build();

  const document = SwaggerModule.createDocument(app, config);

  // Integrasi ZappsDocs di Express
  app.use(
    '/zappsdocs',
    zappsDocsExpress('/zappsdocs', document, {
      title: 'User Service Docs',
      servers: [
        { url: 'http://localhost:3000', description: 'Local' },
      ],
      auth: { type: 'bearer' },
    }),
  );

  await app.listen(3000);
}

bootstrap();

5. Opsi Konfigurasi ZappsDocs

Semua opsi dikirim sebagai ZappsDocsOptions melalui helper zappsDocsFastify / zappsDocsExpress.

Tipe lengkapnya dapat dilihat di src/types/index.ts:

export interface ZappsDocsOptions {
  spec?: any;                                  // Diisi otomatis oleh server helper
  title?: string;                              // Judul di header dan tab browser
  description?: string;                        // Deskripsi singkat API
  version?: string;                            // Versi API
  theme?: 'light' | 'dark' | 'system';         // Tema UI
  layout?: 'modern' | 'classic';               // Layout UI
  responseMode?: 'tabs' | 'cards';             // Cara menampilkan definisi responses
  servers?: { url: string; description?: string }[];
  globalHeaders?: Record<string, string>;      // Header default untuk "Try It"
  auth?: {
    type: 'bearer' | 'basic' | 'apiKey';
    value?: string;                            // Default token/API key
    headerName?: string;                       // Nama header untuk apiKey/basic (jika perlu)
  };
  container?: string | HTMLElement;            // Selector/element container DOM (default: '#app')
}

Penjelasan beberapa opsi penting:

• theme

  • 'light': selalu mode terang
  • 'dark': selalu mode gelap
  • 'system': mengikuti preferensi OS/browser

• layout

  • 'modern': UI seperti panel kiri-kanan (default)
  • 'classic': tata letak yang lebih mendekati swagger klasik (jika di-support)

• responseMode

  • 'tabs' (default): status code menjadi judul tab, isi JSON di dalam satu card.
  • 'cards': setiap status code ditampilkan sebagai card terpisah (stack), mirip versi awal.

• servers

  • Daftar server base URL yang akan muncul di dropdown Server di kanan atas.

  • Contoh:

    servers: [
      { url: 'https://api.mycompany.com', description: 'Production' },
      { url: 'https://staging-api.mycompany.com', description: 'Staging' },
    ];

• globalHeaders

  • Header yang akan selalu ikut dikirim ketika pakai fitur Execute Request.

  • Contoh:

    globalHeaders: {
      'X-Requested-By': 'ZappsDocs',
    },

• auth

  • Mengatur cara pengisian token di UI:

    auth: {
      type: 'bearer',       // bearer | basic | apiKey
      value: 'TOKEN_AWAL',  // optional, bisa dikosongkan
    }

  • ZappsDocs akan membaca components.securitySchemes dari OpenAPI spec, lalu menyesuaikan form Auth di sidebar.

6. Cara Kerja Fitur "Try It" (Execute Request)

Di panel kanan ZappsDocs ada tombol Execute Request yang akan mengirim HTTP request ke server yang dipilih di dropdown Server.

Secara umum alurnya:

1. Pemilihan endpoint

   • Klik endpoint di sidebar kiri, ZappsDocs akan menampilkan path dan method (GET, POST, dst) beserta parameter.

2. Pengisian parameter

   • Path params: akan di-substitusi ke URL (misal /users/{id}).
   • Query params: ditambahkan sebagai query string.
   • Header params: ditambahkan ke header request.

3. Request Body (untuk POST/PUT/PATCH)

   • Textarea JSON akan dikirim sebagai body request dengan header Content-Type: application/json.

4. Auth dan Global Headers

   • Token/API key yang diisi di modal Auth akan digunakan berdasarkan securitySchemes di spec (Bearer, API Key, dsb).
   • globalHeaders dari ZappsDocsOptions akan ikut disertakan.

5. Response

   • Bagian bawah kanan akan menampilkan:
     • Status code & status text (200 OK, 400 Bad Request, dst)
     • Body response (JSON atau text)

Penting: base URL yang digunakan adalah salah satu dari servers (dari spec atau dari options). Pastikan URL tersebut bisa diakses dari browser (CORS, domain, dll).

7. Mengatur Contoh Response (Schemas & Examples)

Panel Responses di UI menampilkan contoh JSON berdasarkan schema di OpenAPI. Generator contoh di ZappsDocs akan:

• Menggunakan example jika tersedia
• Jika tidak ada, menggunakan default
• Jika keduanya tidak ada, akan membuat dummy value berdasarkan type:
  • string → "string"
  • number/integer → 0
  • boolean → false
  • array → [<contoh item>]
  • object → properti diisi contoh rekursif

Contoh definisi di NestJS:

export class ErrorResponseDto {
  @ApiProperty({ example: false })
  status: boolean;

  @ApiProperty({ example: 400 })
  code: number;

  @ApiProperty({ example: 'Bad Request' })
  error: string;

  @ApiProperty({ example: 'Code and Client ID are required' })
  message: string | string[];
}

Dengan definisi tersebut, ZappsDocs akan menampilkan contoh:

{
  "status": false,
  "code": 400,
  "error": "Bad Request",
  "message": "Code and Client ID are required"
}

Jika kamu ingin contoh berbeda tiap status code, gunakan examples di OpenAPI atau definisikan schema per response secara lebih spesifik di controller.

8. Kustomisasi Lanjutan

Beberapa hal yang dapat dikustom lebih jauh:

• Tema dan layout
  Atur theme dan layout di ZappsDocsOptions.

• Mode response (tabs/cards)
  Atur responseMode untuk mengubah tampilan definisi response:

  responseMode: 'tabs',   // status code sebagai tab (recommended)
  // atau
  responseMode: 'cards',  // satu card per status code (stack)

• Penyesuaian CSS tambahan
  Jika kamu menyajikan ZappsDocs lewat HTML custom sendiri, kamu bisa menambahkan stylesheet tambahan di luar zapps-docs.css.

9. Ringkasan Singkat

1. Install:

   pnpm add zappsdocs

2. Generate OpenAPI document dengan @nestjs/swagger.

3. Di main.ts, integrasikan:

   • zappsDocsFastify(fastifyInstance, '/zappsdocs', document, options)
     atau
   • zappsDocsExpress('/zappsdocs', document, options)

4. Akses dokumentasi di browser:

   • http://localhost:3000/zappsdocs

Dengan langkah-langkah ini, ZappsDocs siap dipakai sebagai dokumentasi API interaktif untuk project NestJS kamu.