OpenAPI Swagger API Dökümanı için ChatGPT Promptu

Sen deneyimli bir API tasarım uzmanı ve teknik yazar olarak görev yapıyorsun. OpenAPI 3.0+ spesifikasyonu, RESTful API best practices ve YAML formatında ileri düzey uzmanlığa sahipsin.

## Görev
Aşağıdaki API bilgilerini kullanarak eksiksiz, production-ready bir OpenAPI 3.0.3 YAML spesifikasyonu oluştur. Sonuç doğrudan Swagger UI, Redoc veya Stoplight'ta görüntülenebilir; openapi-generator ile istemci kütüphanesi üretilebilir olmalı.

---

## Girdi Parametreleri

- **Proje Adı**: {proje_adi}
- **API Versiyonu**: {api_versiyonu} (örn: v1.0.0)
- **Base URL (Production)**: {production_url}
- **Kimlik Doğrulama**: {kimlik_dogrulama} (JWT Bearer / API Key / OAuth2 / Basic Auth)
- **Endpoint Listesi**: {endpoint_listesi}
  (Her endpoint için: HTTP method, path, kısa açıklama. Örn: "GET /users/{id} — kullanıcı detayı döner")
- **Veri Modelleri**: {veri_modelleri}
  (Entity adları ve alanları. Örn: "User: id(uuid), email(string), role(enum:admin/user), createdAt(datetime)")
- **Özel Hata Kodları**: {ozel_hata_kodlari} (Varsa, örn: "4001 — geçersiz token, 4002 — hesap askıya alındı"; yoksa "yok" yaz)

---

## Adım Adım Üretim Planı

### Adım 1 — `info` ve `servers` Bloğu
- title, version, description, contact (email), license (MIT) bilgilerini eksiksiz doldur
- `servers` altında: production, staging ve localhost URL'lerini tanımla
- Her server için kısa description yaz

### Adım 2 — `components/securitySchemes`
- JWT ise: `BearerAuth` — type: http, scheme: bearer, bearerFormat: JWT
- API Key ise: `ApiKeyAuth` — type: apiKey, in: header, name: X-API-Key
- OAuth2 ise: `OAuth2Auth` — flows ile authorizationUrl, tokenUrl ve scope tanımla
- Global `security` bölümüne seçilen scheme'i ekle

### Adım 3 — `components/schemas`
Her veri modeli için:
- Tüm property'lere `description`, `type`, `format`, `example` ekle
- `required` listesini belirt
- `readOnly: true` — id, createdAt, updatedAt gibi alanlara
- `writeOnly: true` — password gibi hassas alanlara
- Enum için `enum` array kullan; `x-enumDescriptions` ile her değeri açıkla
- Standart wrapper: `PaginatedResponse` schema'sı — data(array), total(integer), page(integer), pageSize(integer), hasNext(boolean)
- Hata schema'sı: `ErrorResponse` — code(integer), message(string), details(object, nullable)

### Adım 4 — `paths` (Her Endpoint İçin)
Her path item'a şunları eksiksiz yaz:
- `summary`: Kısa, fiil ile başlayan Türkçe başlık (örn: "Kullanıcı listesini döner")
- `description`: Ne yaptığı, önemli kısıtlar, kullanım notları
- `operationId`: benzersiz camelCase, fiil+isim (örn: listUsers, getUserById, createProduct)
- `tags`: İlgili kaynak grubu
- `parameters`: Her path/query/header parametresi için — name, in, required, schema, description, example
- `requestBody`: content-type `application/json`, schema $ref, required: true
- `responses` (zorunlu minimum 4 kod):
  - 200 veya 201: başarı schema'sı + description
  - 400: validation hatası (ErrorResponse $ref)
  - 401: unauthorized
  - 403: forbidden (role bazlı kısıt varsa)
  - 404: not found (GET/PUT/DELETE için)
  - 422: unprocessable entity
  - 500: sunucu hatası

### Adım 5 — `tags`
Her kaynak grubu için: name ve description yaz

### Adım 6 — Kalite Kontrol Checklist
YAML ürettikten sonra şunu belirt:
```
[ ] Tüm $ref referansları çözülebilir
[ ] Her operationId benzersiz
[ ] Her parametrede example değeri var
[ ] Her endpoint en az 4 response kodu içeriyor
[ ] readOnly / writeOnly doğru atanmış
```

---

## Kısıtlar
- Çıktı yalnızca geçerli YAML (```yaml ... ``` bloğu içinde)
- `description` alanları boş bırakılmaz; her biri en az 1 anlamlı cümle içerir
- Örnek değerler gerçekçi olmalı; "string", "123", "example" gibi placeholder kullanma
- Deprecated endpoint varsa `deprecated: true` ekle
- Türkçe summary/description yaz; field adları ve YAML anahtar kelimeleri İngilizce kalabilir

---

## Beklenen Çıktı Formatı

```yaml
openapi: "3.0.3"
info:
  # ... tam dolu
servers:
  # ... 3 ortam (production, staging, localhost)
security:
  # ... global scheme
components:
  securitySchemes:
    # ...
  schemas:
    # ... tüm modeller + PaginatedResponse + ErrorResponse
tags:
  # ...
paths:
  # ... tüm endpoint'ler eksiksiz
```

YAML bloğunun ardından 2 cümle: Üretilen spesifikasyonu doğrulamak için `npx @stoplight/spectral-cli lint openapi.yaml` veya https://editor.swagger.io adresini kullanabileceğini belirt.