A7

7-amaliy mashg‘ulot · 7-mavzu · 2 soat · Korxona ilovalarini dasturlash

REST API: JWT va OpenAPI hujjatlari

Jamoa loyihasi (OmborPro) bosqichi, 5 ta amaliy PHP topshiriq va 3 ta ma’ruzadagi mashq. Yo‘riqnoma bo‘yicha loyihada ishlang, havolani topshiring va PHP topshiriqlarni yeching — server yashirin testlar bilan tekshiradi, o‘qituvchi baho qo‘yadi.

Mashg‘ulot maqsadi

  • Yaratish — mahsulotlar va buyurtmalar uchun /api/v1 REST endpointlarini (API Resource, Form Request)
  • Sozlash — php-open-source-saver/jwt-auth orqali JWT autentifikatsiya: login, refresh, logout
  • Qo‘llash — sahifalash, filtrlash va RFC 7807 formatidagi yagona xato javoblarini
  • Hujjatlash — API ni Scribe yordamida OpenAPI spetsifikatsiyasi va /docs sahifasi bilan
  • Tekshirish — endpointlarni Postman kolleksiyasi va newman orqali

1. 1-qadam. API skeleti: marshrut, Resource, validatsiya

install:api · Api/V1 controllerlar · ProductResource · OrderResource · 201/422/409

Jamoa loyihangizda yangi feature/api-v1 branch oching. php artisan install:api buyrug‘ini bajaring — u routes/api.php ni yaratadi va bootstrap/app.php ga ulaydi. Sanctum migratsiyasini ham qo‘shadi; uni qoldirish mumkin (keyinroq integratsiya tokenlari uchun kerak bo‘lishi mumkin). So‘ng php artisan make:controller Api/V1/ProductController --api --model=Product va Api/V1/OrderController ni yarating: --api bayrog‘i faqat index, store, show, update, destroy metodlarini qo‘shadi.

Resource lar: php artisan make:resource ProductResource, CategoryResource, OrderResource, OrderItemResource, CounterpartyResource. Har birida faqat mijozga kerakli maydonlarni yozing; pul maydonlari (price, total) satr bo‘lib chiqishi uchun modelda decimal:2 cast borligini tekshiring, buyurtma holati enum bo‘lsa ->value bilan bering. Relationlarni faqat whenLoaded() orqali qo‘shing va controllerda with() / load() bilan oldindan yuklang.

Buyurtma yaratish endpointi biznes-logikani qayta yozmaydi: “Biznes-logika va servis qatlami” mavzusidagi OrderService ni chaqiradi. StoreOrderRequest (6-mavzudan) items.*.product_id va items.*.quantity qoidalarini tekshiradi, controller esa servis natijasini OrderResource ga o‘raydi. confirm amal-endpointi OrderService ni chaqiradi; qoldiq yetarli bo‘lmasa servis InsufficientStockException tashlaydi — uni bootstrap/app.php da 409 problem+json ga aylantiring.

Har bir endpointni curl bilan sinab ko‘ring: muvaffaqiyatli holat, validatsiya xatosi (422), topilmagan resurs (404) va biznes to‘qnashuvi (409). Barcha so‘rovlarda Accept: application/json sarlavhasi bo‘lsin. php artisan route:list --path=api/v1 chiqishini README ga qo‘shing — bu API ning birinchi, eng qisqa hujjati.

TERMINAL

Skelet buyruqlari

php artisan install:api
php artisan make:controller Api/V1/ProductController --api
php artisan make:controller Api/V1/OrderController --api
php artisan make:resource ProductResource
php artisan make:resource OrderResource
php artisan make:resource OrderItemResource
php artisan route:list --path=api/v1
▶ Natija
INFO  API scaffolding installed. Please add the
[Laravel\Sanctum\HasApiTokens] trait to your User model.
INFO  Controller [app/Http/Controllers/Api/V1/ProductController.php] created successfully.
  • install:api — routes/api.php + Sanctum; /api prefiksi avtomatik
  • --api — 5 ta API metodi; --model=Product bilan Product $product binding
  • make:resource — app/Http/Resources ichida JsonResource sinfi
OrderResource

Buyurtma ko‘rinishi

class OrderResource extends JsonResource
{
    public function toArray(Request $request): array
    {
        return [
            'id' => $this->id,
            'number' => $this->number,          // BY-2026-000123
            'status' => $this->status->value,   // OrderStatus enum
            'counterparty' => new CounterpartyResource(
                $this->whenLoaded('counterparty')),
            'total' => $this->total,            // "1155000.00"
            'currency' => $this->currency,
            'items' => OrderItemResource::collection(
                $this->whenLoaded('items')),
            'created_at' => $this->created_at->toIso8601String(),
        ];
    }
}
▶ Natija
{"data": {"id": 42, "number": "BY-2026-000042", "status": "draft",
  "total": "1155000.00", "currency": "UZS",
  "items": [{"product_id": 15, "quantity": 3, "price": "385000.00"}]}}
  • $this->status->value — enum o‘rniga uning satr qiymati: draft, confirmed...
  • whenLoaded('items') — ro‘yxatda qatorlarsiz, show da qatorlar bilan
  • OrderItemResource::collection — ichki to‘plam ham Resource orqali
CONTROLLER

Servisni chaqiruvchi store va confirm

public function store(StoreOrderRequest $request, OrderService $orders)
{
    $data = OrderData::fromArray($request->validated());
    $order = $orders->create($data);

    return (new OrderResource($order->load('items')))
        ->response()
        ->header('Location', route('v1.orders.show', $order));
}

public function confirm(Order $order, OrderService $orders)
{
    $this->authorize('confirm', $order);         // OrderPolicy
    $order = $orders->confirm($order);           // 409 bo‘lishi mumkin

    return new OrderResource($order->load('items'));
}
▶ Natija
POST /api/v1/orders           → 201 Created
POST /api/v1/orders/42/confirm → 200 {"data": {"status": "confirmed"}}
POST /api/v1/orders/42/confirm → 409 problem+json (holat o‘tishi taqiqlangan)
  • OrderData::fromArray — 2-mavzudagi DTO — servis massiv emas, aniq tur oladi
  • $this->authorize() — 5-mavzudagi OrderPolicy; ruxsat yo‘q — 403
  • $orders->confirm() — tranzaksiya, invariantlar va holat o‘tishi — servisda

2. 2-qadam. JWT autentifikatsiya

jwt-auth o‘rnatish · api guard · JWTSubject · login, refresh, logout

Paketni o‘rnating: composer require php-open-source-saver/jwt-auth. Konfiguratsiyani nashr qiling: php artisan vendor:publish --provider="PHPOpenSourceSaver\JWTAuth\Providers\LaravelServiceProvider" — config/jwt.php paydo bo‘ladi. php artisan jwt:secret buyrug‘i .env ga tasodifiy JWT_SECRET yozadi. Bu kalit hech qachon repozitoriyga tushmasligi kerak: .env.example da faqat bo‘sh JWT_SECRET= qatori qoladi.

config/auth.php da yangi guard qo‘shing: 'api' => ['driver' => 'jwt', 'provider' => 'users']. User modeli PHPOpenSourceSaver\JWTAuth\Contracts\JWTSubject interfeysini amalga oshiradi: getJWTIdentifier() foydalanuvchi ID sini, getJWTCustomClaims() esa qo‘shimcha da’volarni (masalan, rollar ro‘yxati) qaytaradi. Da’volarga faqat maxfiy bo‘lmagan, kichik ma’lumot yozing — har bir so‘rovda token bilan birga yuboriladi.

Api/V1/AuthController da uchta metod: login (auth('api')->attempt()), refresh (auth('api')->refresh() — yangi token), logout (auth('api')->logout() — tokenni qora ro‘yxatga yozadi, javob 204). me metodi joriy foydalanuvchini UserResource orqali qaytarishi mumkin. Login marshrutiga throttle:5,1 qo‘ying, nofaol (is_active = false) foydalanuvchiga token bermang.

config/jwt.php da ttl (daqiqa) ni 30–60 atrofida qoldiring, refresh_ttl — necha daqiqa ichida tokenni yangilash mumkinligi. Tekshirish: tokensiz GET /api/v1/products → 401, login → token, token bilan → 200, logout dan keyin shu token bilan → 401. Rollar bo‘yicha ruxsatlar (5-mavzudagi spatie/laravel-permission va Policy) API da ham xuddi web dagidek ishlaydi.

TERMINAL

jwt-auth ni o‘rnatish

composer require php-open-source-saver/jwt-auth
php artisan vendor:publish \
--provider="PHPOpenSourceSaver\JWTAuth\Providers\LaravelServiceProvider"
php artisan jwt:secret
▶ Natija
jwt-auth secret [...] set successfully.

# .env
JWT_SECRET=<tasodifiy 64 belgi — repozitoriyga tushmaydi>
  • vendor:publish — config/jwt.php — ttl, refresh_ttl, algo, blacklist
  • jwt:secret — HS256 uchun sir kalit .env ga yoziladi
  • .env.example — faqat JWT_SECRET= (qiymatsiz) qatori
User MODELI

JWTSubject va api guard

// config/auth.php
'guards' => [
    'web' => ['driver' => 'session', 'provider' => 'users'],
    'api' => ['driver' => 'jwt', 'provider' => 'users'],
],

// app/Models/User.php
class User extends Authenticatable implements JWTSubject
{
    public function getJWTIdentifier()
    {
        return $this->getKey();
    }
    public function getJWTCustomClaims(): array
    {
        return ['roles' => $this->getRoleNames()];
    }
}
▶ Natija
Token payload: {"iss": ".../api/v1/auth/login", "iat": ..., "exp": ...,
 "sub": "7", "jti": "...", "roles": ["menejer"]}
  • 'driver' => 'jwt' — auth:api middleware shu guard bilan ishlaydi
  • getJWTIdentifier() — sub da’vosi — foydalanuvchi ID si
  • getJWTCustomClaims() — qo‘shimcha da’vo: spatie rollari (maxfiy emas)
TEKSHIRUV

Autentifikatsiya ssenariysi

  1. Tokensiz — GET /api/v1/products → 401 problem+json
  2. Login — POST /api/v1/auth/login → 200, access_token, expires_in
  3. Token bilan — Authorization: Bearer ... → 200 va mahsulotlar ro‘yxati
  4. Rol tekshiruvi — omborchi tokeni bilan POST /orders/42/confirm → 403
  5. Logout — POST /api/v1/auth/logout → 204; eski token bilan → 401

3. 3-qadam. OpenAPI hujjati va Postman kolleksiyasi

Scribe · docblock teglari · /docs · collection.json · newman

composer require --dev knuckleswtf/scribe va php artisan vendor:publish --tag=scribe-config. config/scribe.php da: title — “OmborPro API”, routes.*.match.prefixes — ['api/*'], auth.enabled va auth.default — true, auth.in — bearer, auth.name — Authorization. postman.enabled va openapi.enabled yoqilgan bo‘lsin. Hujjat sahifasi type sozlamasiga qarab /docs marshrutida (laravel) yoki public/docs papkasida (static) yaratiladi.

Controllerlarga docblock yozing: har bir metod uchun birinchi qatorda qisqa nom, keyin tavsif va biznes-qoidalar, so‘ng @group, @authenticated, @urlParam, @queryParam. Ro‘yxat va bitta resurs javoblari uchun @apiResourceCollection / @apiResource va @apiResourceModel — buning uchun modellarning factory lari ishlashi kerak (3-mavzu). Xato javoblari uchun @response 409 {...} namunasini qo‘lda qo‘shing — mijoz problem+json formatini hujjatda ko‘rsin.

php artisan scribe:generate dan keyin /docs ni oching va har bir endpointni “Try it out” bilan sinang. Postman da /docs.postman (yoki yaratilgan collection.json) ni import qiling, local muhitini yarating: baseUrl = https://omborpro.test, token — bo‘sh. Login so‘rovining Tests bo‘limiga tokenni muhitga yozuvchi skript qo‘shing; kolleksiya darajasida avtorizatsiyani Bearer {{token}} qilib belgilang.

Kolleksiya va muhit faylini repozitoriyga eksport qiling: docs/postman/omborpro.postman_collection.json va docs/postman/local.postman_environment.json (tokensiz!). npx newman run ... buyrug‘i barcha so‘rovlarni ketma-ket bajarib, testlar natijasini chiqaradi — bu natija skrinshotini PR tavsifiga qo‘shing.

POSTMAN TESTS

Login javobidan tokenni olish

// Login so‘rovi → Tests (Post-response) bo‘limi
pm.test("Login muvaffaqiyatli", function () {
    pm.response.to.have.status(200);
});
const body = pm.response.json();
pm.environment.set("token", body.access_token);

// Kolleksiya → Authorization: Bearer Token = {{token}}
// Mahsulot yaratish so‘rovi → Tests
pm.test("201 va Location", function () {
    pm.response.to.have.status(201);
    const loc = pm.response.headers.get("Location");
    pm.expect(loc).to.include("/products/");
});
▶ Natija
POST Login            ✓ Login muvaffaqiyatli
GET  Mahsulotlar      ✓ 200
POST Mahsulot yaratish ✓ 201 va Location
  • pm.environment.set — token muhit o‘zgaruvchisiga yoziladi
  • {{token}} — kolleksiyadagi barcha so‘rovlar shu tokenni ishlatadi
  • pm.test — har bir so‘rov uchun kutilgan status va sarlavhalar
TERMINAL

Hujjat yaratish va kolleksiyani yugurtirish

composer require --dev knuckleswtf/scribe
php artisan vendor:publish --tag=scribe-config
php artisan scribe:generate

npx newman run docs/postman/omborpro.postman_collection.json \
  -e docs/postman/local.postman_environment.json
▶ Natija
┌─────────────────────────┬──────────┬──────────┐
│                         │ executed │   failed │
├─────────────────────────┼──────────┼──────────┤
│              requests   │       12 │        0 │
│            assertions   │       18 │        0 │
└─────────────────────────┴──────────┴──────────┘
  • scribe:generate — /docs, /docs.openapi, /docs.postman yangilanadi
  • newman run — kolleksiyani buyruq qatorida yugurtiradi
  • -e ...environment.json — muhit: baseUrl, token (repozitoriyda tokensiz)
MINIMAL API

Topshirishdagi endpointlar ro‘yxati

EndpointMetodKutilgan status
/api/v1/auth/loginPOST200 / 401 / 422 / 429
/api/v1/auth/refresh, /logoutPOST200 / 204
/api/v1/productsGET, POST200 (sahifalangan) / 201 / 422
/api/v1/products/{product}GET, PUT, DELETE200 / 204 / 404
/api/v1/ordersGET, POST200 / 201 / 422
/api/v1/orders/{order}/confirmPOST200 / 403 / 409
Har bir qator Postman da kamida bitta muvaffaqiyatli va bitta xato so‘rov bilan qoplansin.

Loyiha bosqichi: natija va topshirish

Natija: mahsulotlar va buyurtmalar uchun JWT bilan himoyalangan /api/v1 REST API, yagona problem+json xato formati, Scribe yaratgan OpenAPI hujjati (/docs) va newman bilan muvaffaqiyatli o‘tadigan Postman kolleksiyasi.

Baholash mezonlari
  • routes/api.php da v1 guruhi, Route::apiResource (products, orders) va orders/{order}/confirm amal-endpointi bor.
  • Barcha javoblar API Resource orqali; parol, deleted_at kabi maydonlar chiqmaydi, pul satr ko‘rinishida.
  • Ro‘yxatlar sahifalangan (data, links, meta), per_page 1–100 bilan cheklangan, filtr/saralash oq ro‘yxat bilan.
  • Yaratishda 201 + Location, validatsiyada 422, biznes-xatoda 409 problem+json, ruxsat yo‘qligida 403.
  • JWT: login, refresh, logout ishlaydi; JWT_SECRET repozitoriyda yo‘q; login throttle bilan himoyalangan.
  • /docs sahifasi va OpenAPI fayli Scribe bilan yaratilgan, endpointlar guruhlangan va izohlangan.
  • Postman kolleksiyasi va muhit fayli repozitoriyda; newman run 0 ta xato bilan o‘tadi.

📤 GitHub repozitoriyingizdagi feature/api-v1 Pull Request havolasini yuboring. PR tavsifida route:list --path=api/v1 chiqishi, /docs sahifasi skrinshoti va newman run natijasi bo‘lsin.

?

Qanday ishlaydi. Chapdan topshiriqni tanlang, shartni o‘qing va shartdagi imzo bo‘yicha sof PHP funksiya yoki sinf yozing (Laravelsiz). ▶ Sinab ko‘rish — pastdagi chaqiruv ifodasini kodingiz bilan bajaradi (baholanmaydi). ✓ Topshirish — server kodni namunaviy va yashirin testlar bilan tekshiradi; natija o‘qituvchiga ko‘rinadi.

Yechildi 0 / 8
Ball 0

💡 Maslahat

PHP 8.3 kodi · avtomatik saqlanadi