Postman Collection

Postman Collection

Overview

Merq menyertakan tooling untuk menghasilkan Postman Collection secara otomatis dari Swagger/OpenAPI spec yang di-generate oleh swaggo/swag. Collection dihasilkan oleh binary terpisah (cmd/postman-injector) dan disimpan di merq-backend/docs/postman/.

File Lokasi

File	Path di Repo
Postman Collection	merq-backend/docs/postman/merq-api-collection.json
Postman Environment	(dihasilkan saat run, tidak di-commit)
Swagger JSON	merq-backend/docs/swagger.json
Swagger YAML	merq-backend/docs/swagger.yaml

Catatan: File merq-local-environment.json dihasilkan ke docs/postman/merq-local-environment.json saat menjalankan postman-injector, tapi tidak di-commit ke repo. Harus di-generate secara lokal.

Import ke Postman

Import Collection

1. Buka Postman
2. Klik Import (pojok kiri atas)
3. Pilih tab File
4. Upload merq-backend/docs/postman/merq-api-collection.json
5. Klik Import

Import Environment

1. Generate environment file dulu (lihat bagian Regenerasi di bawah)
2. Di Postman, buka tab Environments (sidebar kiri)
3. Klik Import
4. Upload merq-backend/docs/postman/merq-local-environment.json
5. Pilih environment dari dropdown kanan atas

Environment Variables

Setelah import, environment berisi variabel berikut:

Variable	Deskripsi	Contoh Nilai
base_url	Base URL API	http://localhost:8080/api
access_token	JWT access token (diisi manual setelah login)	eyJhbGciOiJIUzI1NiIs...
refresh_token	JWT refresh token (diisi manual setelah login)	eyJhbGciOiJIUzI1NiIs...
workspace_id	ID workspace yang aktif	1

Konfigurasi base_url sesuai environment:

# Local
base_url = http://localhost:8080/api

# Staging
base_url = https://api-staging.merq.app/api

# Production
base_url = https://api.merq.app/api

Alur Pertama Kali

1. Import collection dan environment
2. Set environment aktif di Postman
3. Buka folder Auth → kirim request Login
4. Salin access_token dari response dan paste ke variabel access_token di environment
5. Request selanjutnya sudah otomatis menggunakan token di header Authorization: Bearer <token>

Contoh request body login:

{
  "email": "admin@example.com",
  "password": "password"
}

Regenerasi Collection

Collection di-generate dari Swagger spec. Workflow-nya dua langkah:

Langkah 1: Generate/Update Swagger Spec

cd merq-backend

# Install swag CLI jika belum ada
go install github.com/swaggo/swag/cmd/swag@latest

# Generate docs/swagger.json dan docs/swagger.yaml
swag init -g cmd/server/main.go -o docs

Langkah 2: Generate Postman Collection dari Swagger

cd merq-backend

# Generate collection ke docs/postman/merq-api-collection.json
# dan environment ke docs/postman/merq-local-environment.json
go run cmd/postman-injector/main.go

# Atau dengan path kustom
go run cmd/postman-injector/main.go \
  -swagger docs/swagger.json \
  -output docs/postman/merq-api-collection.json \
  -env-output docs/postman/merq-local-environment.json

Kapan Perlu Regenerasi

• Setelah menambah endpoint baru
• Setelah mengubah request/response DTO
• Setelah mengubah route parameter
• Sebelum merilis versi API baru

Format Response API

Semua response menggunakan utils.HandleResponse dengan struktur konsisten:

Sukses (200/201)

{
  "code": 200,
  "status": "SUCCESS",
  "message": "MODULE_LIST",
  "data": { ... }
}

Error Validasi (400)

{
  "code": 400,
  "status": "BAD_REQUEST",
  "message": "Validation failed",
  "errors": [...]
}

Unauthorized (401)

{
  "code": 401,
  "status": "UNAUTHORIZED",
  "message": "Invalid or expired token"
}

Forbidden (403)

{
  "code": 403,
  "status": "FORBIDDEN",
  "message": "Insufficient permissions"
}

Not Found (404)

{
  "code": 404,
  "status": "NOT_FOUND",
  "message": "MODULE_NOT_FOUND"
}

Internal Error (500)

{
  "code": 500,
  "status": "INTERNAL_SERVER_ERROR",
  "message": "An unexpected error occurred"
}