Quick Start

Hướng dẫn nhanh để FE bắt đầu tích hợp Cohost API.

Cài đặt

1. Kiểm tra Orval Config

Trong cohost-fe/orval.config.ts, đảm bảo đã cấu hình đúng:

// orval.config.ts
export default {
  cohost: {
    output: {
      target: 'src/generated/api',
      client: 'react-query',
      // ...
    },
    input: {
      target: 'https://api.cohost.vn/openapi.json',
    },
  },
};

2. Generate API Client

cd cohost-fe
npm run generate-api

3. Cấu trúc Generated Code

Sau khi generate, cấu trúc thư mục:

src/generated/api/
├── auth/
│   ├── auth.ts              # Auth endpoints
│   └── index.ts
├── listings/
│   ├── listings.ts          # Listing CRUD
│   └── index.ts
├── bookings/
│   ├── bookings.ts
│   └── index.ts
├── models/                  # TypeScript types
│   ├── Listing.ts
│   ├── Booking.ts
│   └── index.ts
└── index.ts                 # Export all

Sử dụng API trong Component

Ví dụ: Lấy danh sách Listings

'use client';

import { useGetListingsApiV1ListingsGet } from '@/generated/api/listings/listings';

export default function ListingPage() {
  const { data, isLoading, error } = useGetListingsApiV1ListingsGet({
    page: 1,
    limit: 20,
  });

  if (isLoading) return <div>Loading...</div>;
  if (error) return <div>Error: {error.message}</div>;

  return (
    <ul>
      {data?.items?.map((listing) => (
        <li key={listing.id}>{listing.name}</li>
      ))}
    </ul>
  );
}

Ví dụ: Tạo Booking

'use client';

import { useCreateExternalBookingApiV1ExternalBookingsPost } from '@/generated/api/bookings/bookings';

function BookingForm({ listingId }: { listingId: string }) {
  const createBooking = useCreateExternalBookingApiV1ExternalBookingsPost();

  const handleSubmit = async (formData: BookingFormData) => {
    try {
      const result = await createBooking.mutateAsync({
        data: {
          listing_id: listingId,
          check_in: formData.checkIn,
          check_out: formData.checkOut,
          guests: formData.guests,
          guest_info: {
            name: formData.name,
            phone: formData.phone,
            email: formData.email,
          },
        },
      });

      console.log('Booking created:', result);
    } catch (error) {
      console.error('Booking failed:', error);
    }
  };

  return <form onSubmit={handleSubmit}>...</form>;
}

API Tags theo OpenAPI

Dưới đây là danh sách các nhóm API (tags) từ OpenAPI spec:

Tag	Mô tả	Module
auth	Authentication	auth/auth.ts
listings	Listing CRUD	listings/listings.ts
bookings	Booking management	bookings/bookings.ts
cart	Shopping cart	cart/cart.ts
checkout	Checkout flow	checkout/checkout.ts
channels	Chat/Messaging	channels/channels.ts
amenities	Amenities catalog	amenities/amenities.ts
catalogs	Catalog management	catalogs/catalogs.ts
financial	Financial/Payments	financial/financial.ts
teams	Team management	teams/teams.ts
notifications	Notifications	notifications/notifications.ts
reviews	Reviews	reviews/reviews.ts
search	Search	search/search.ts
external	External/OTA API	external/external.ts

Tiếp theo

• Authentication: Tích hợp Auth0
• Common Patterns: Pattern thường dùng