# REST Api Dokümantasyonu Nasıl Oluşturulur?

> Bu yazı RESTFul Api Tasarım İncelikleri serisinin bir parçası niteliğindedir. Eğer okumadıysanız önce serinin diğer yazılarını okumanızı tavsiye ederim.

> 💡 **Özet (TL;DR):**
> - **OpenAPI (Swagger):** Sektör standardıdır. API şemalarını JSON/YAML olarak tanımlayıp dokümantasyon (Swagger UI/Redoc) ve otomatik istemci kodu üretmeyi sağlar.
> - **Postman:** Takım çalışması, otomatik test senaryoları ve mock sunucular için zengin bir platformdur.
> - **Modern Yaklaşım:** Günümüzde dokümantasyonu elle yazmak yerine, FastAPI (Python), NestJS (TS) veya Fastify gibi kütüphanelerle koddan otomatik OpenAPI şemaları türetmek tercih edilir.
> - **Modern İstemciler:** Advanced Rest Client (ARC) yerine artık Git dostu ve açık kaynaklı **Bruno** ya da VS Code entegreli **Thunder Client** gibi modern araçlar kullanılmaktadır.

Bu yazı RESTFul Api Tasarım İncelikleri serisinin bir parçası niteliğindedir. Eğer okumadıysanız önce serinin diğer yazılarını okumanızı tavsiye ederim.

- [REST Api Temelleri](/tr/rest-api-tasarimi#rest-api-temelleri)
- [REST API Çıktı Formatı Ne Olmalı?](/tr/rest-api-tasarimi#cikti-formati)
- [REST API URI yapısı nasıl olmalı?](/tr/rest-api-uri-yapisi-nasil-olmali)
- [REST Api HATEOAS kavramı nedir? (Bu diziye sonradan eklendi)](/tr/restapi-ve-hateoas-kavrami)
- [REST API kimlik doğrulama nasıl yapılır? (Authentication)](/tr/rest-api-kimlik-dogrulama-nasil-yapilir)
- [REST API hata yönetimi nasıl yapılır? (Error Handling)](/tr/rest-api-hata-yonetimi)
- [REST API güvenliği nasıl sağlanır? (Security)](/tr/rest-api-guvenligi-nasil-saglanir)
- [REST API Dokümantasyon (Documentation) ve Test'i nasıl yapılır?](/tr/rest-api-dokumantasyonu-nasil-yapilir)
- [Örnek REST API Projesi](/tr/full-stack-proje-gelistiriyoruz)

Dokümantasyon oluşturmak, genellikle API'yi kodlamaktan çok daha zor ve ihmal edilen bir süreçtir. Her ne kadar bunu otomatik yaptığını iddia eden kütüphaneler olsa da, bu araçların doğru çıktı verebilmesi için koda eklenmesi gereken açıklamalar (annotations / decorators) bazen manuel doküman yazmak kadar uğraştırıcı olabilir.

İyi bir REST API dokümantasyonunun mutlaka barındırması gereken kritik bilgiler şunlardır:

- **API Uç Noktaları (Endpoints) ve HTTP Metotları:** Hangi kaynaklara hangi URI üzerinden erişiliyor? (`GET /users`, `POST /users` vb.)
- **Parametreler:** Query, Path veya Body içinde hangi parametreler bekliyor? Hangileri zorunlu (required), hangileri isteğe bağlı (optional)? Veri tipleri neler?
- **İstek (Request) Örneği:** Payload içeriği ve HTTP Header bilgileri (örn. `Content-Type: application/json`).
- **Yanıt (Response) Şeması ve Örnekleri:** Başarılı (`200 OK`, `201 Created`) ve hatalı yanıtların gövde (body) yapısı.
- **Hata Yönetimi (Error Codes):** Olası HTTP hata durum kodları (`400`, `401`, `403`, `404`, `500`) ve dönen hata mesajı biçimleri.
- **Kimlik Doğrulama (Authentication & Authorization):** Uç noktaya erişim için JWT Token, API Key veya OAuth2 gerekiyor mu? Gerekiyorsa nasıl gönderilmeli?
- **Hız Sınırları (Rate Limiting):** İstemcilerin dakikada/saniyede yapabileceği maksimum istek sayısı.

---

## API Tasarım Yaklaşımları: Design-First vs. Code-First

API dokümantasyonunu kurgularken iki temel yaklaşımdan biri tercih edilir:

### 1. Design-First (Önce Tasarım)
Kod yazmaya başlamadan önce API kontratının OpenAPI spesifikasyonuna uygun olarak YAML veya JSON formatında tasarlanmasıdır.
- **Avantajı:** Ön yüz (Frontend) ve arka yüz (Backend) geliştiricileri aynı anda, ortak bir kontrat üzerinden çalışmaya başlayabilir. Tasarlanan şema **Prism** gibi mock araçlarıyla anında sahte bir API sunucusuna dönüştürülebilir.
- **Araçlar:** Swagger Editor, Stoplight Studio, Apicurio.

### 2. Code-First (Önce Kod)
Önce backend kodunun yazılması ve kodun içerisindeki tip tanımlamaları, decorator'lar veya yorum satırları vasıtasıyla dokümantasyonun otomatik olarak türetilmesidir.
- **Avantajı:** Kod değiştiğinde dokümantasyon da otomatik olarak güncellenir; kod ile dokümanın senkronizasyonunun bozulması engellenir.
- **Kütüphaneler:** FastAPI (Python - entegre gelir), NestJS (`@nestjs/swagger` - TypeScript), Fastify (`@fastify/swagger` - Node.js), `zircote/swagger-php` (PHP).

---

## Sektör Standardı: OpenAPI ve Swagger

### OpenAPI Nedir?
OpenAPI, RESTful API'lerin dil bağımsız bir şekilde tanımlanmasını sağlayan resmi bir spesifikasyondur. API'nizin tüm girdilerini ve çıktılarını standart bir JSON veya YAML dosyasında açıklar.

### Swagger Nedir?
Swagger, OpenAPI spesifikasyonunu oluşturmak, görselleştirmek ve tüketmek için kullanılan araçlar ekosistemidir (Swagger UI, Swagger Editor, Swagger Codegen).

Aşağıda temel bir kullanıcının bilgilerini dönen API endpoint'ine ait örnek bir **OpenAPI 3.1** YAML şeması yer almaktadır:

```yaml
openapi: 3.1.0
info:
  title: Kullanıcı Yönetim API'si
  version: 1.0.0
paths:
  /users/{id}:
    get:
      summary: Belirli bir kullanıcının detaylarını getirir
      parameters:
        - name: id
          in: path
          required: true
          description: Kullanıcının benzersiz ID değeri
          schema:
            type: integer
      security:
        - BearerAuth: []
      responses:
        '200':
          description: Başarılı istek yanıtı
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                    example: 42
                  name:
                    type: string
                    example: "Evren Bal"
        '401':
          description: Yetkisiz erişim (Token eksik veya geçersiz)
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
```

---

## Modern Dokümantasyon Arayüzleri

OpenAPI YAML/JSON dosyasını hazırladıktan sonra bunu kullanıcıya şık bir arayüzle sunmak gerekir:

1. **Swagger UI:** Sektörün en eski ve en popüler arayüzüdür. İstekleri doğrudan tarayıcı üzerinden tetikleyerek ("Try it out") test etme olanağı tanır.
2. **Redoc:** Özellikle büyük API'ler için harika, modern ve üç panelli (Sol menü, orta içerik, sağ kod blokları) statik bir dokümantasyon arayüzüdür. Okunabilirliği Swagger UI'dan çok daha yüksektir.
3. **Scalar:** Son dönemde popülerliği hızla artan, son derece hızlı, etkileşimli ve şık bir OpenAPI istemcisidir. Doğrudan API test aracı (Rest Client) barındırır.
4. **Stoplight Elements:** Web bileşeni (Web Component) mimarisine sahip, sitenize kolayca entegre edebileceğiniz modern bir alternatiftir.

---

## API Test ve Dokümantasyon Araçları

Dokümantasyonun yanı sıra, geliştirme esnasında API isteklerini test etmek için kullanılan araçlar da büyük önem taşır:

### 1. Postman
API testi, takım içi koleksiyon paylaşımı ve uçtan uca entegrasyon testleri için en yaygın platformdur. JavaScript tabanlı test scriptleri yazmanıza ve CI/CD süreçlerine entegre etmenize (`Newman` veya `Postman CLI` aracılığıyla) olanak tanır. Ancak, son sürümlerde çok fazla bulut tabanlı ve ticari özelliğe odaklandığı için bazı geliştiriciler tarafından ağır bulunmaktadır.

### 2. Bruno (Açık Kaynak & Git Dostu)
Postman'e en güçlü açık kaynaklı alternatiftir. En büyük avantajı, API istek koleksiyonlarını şifreli veya kapalı veri tabanlarında değil, doğrudan projenizin Git deposunda saklanabilecek düz metin formatında (`.bru` dosyaları olarak) kaydetmesidir. Böylece sürüm kontrolü (version control) çok kolaylaşır.

### 3. VS Code Eklentileri (Thunder Client / RapidAPI Client)
Editörden çıkmadan hızlıca istek atmak isteyenler için harika çözümlerdir. Hafif ve pratiktirler.

---

## Karşılaştırma Tablosu

| Araç | Kullanım Amacı | Avantajları | Dezavantajları |
| :--- | :--- | :--- | :--- |
| **OpenAPI / Swagger** | Şema & Görsel Arayüz | Dil bağımsız standart, otomatik kod üretimi, geniş ekosistem | YAML/JSON şemasını elle yazmak karmaşıktır |
| **Postman** | API Testi & Otomasyon | Zengin arayüz, mock sunucular, güçlü test betikleri | Bulut zorunluluğu, ağırlaşan arayüz, takım özellikleri için ücretli olması |
| **Bruno** | Git-Dostu API Testi | Tamamen açık kaynak, koleksiyonları git'te düz metin tutma | Ekosistemi ve entegrasyon araçları Postman kadar geniş değil |

---

## Sıkça Sorulan Sorular (FAQ)

### Üretim (Production) ortamında API dokümantasyonunu nasıl korumalıyız?
Canlı sunucuda tüm API dokümanını herkese açık bırakmak güvenlik riskleri doğurabilir. Bunu önlemek için:
- Swagger/Redoc endpoints arkasına bir **Basic Authentication** (Kullanıcı adı/Şifre) katmanı ekleyin.
- Sadece belirli IP adreslerinden (örn. ofis IP'niz veya VPN) gelen isteklere izin verin.
- Üretim ortamında dokümantasyon endpoint'ini tamamen kapatacak ortam değişkenleri (`ENABLE_SWAGGER=false`) kullanın.

### OpenAPI şemamı kullanarak frontend için nasıl mock sunucu oluştururum?
Eğer elinizde bir OpenAPI spec dosyası (`api.yaml`) varsa, **Prism** kütüphanesini kullanarak saniyeler içinde sahte bir sunucu ayaklandırabilirsiniz:
```bash
npx @stoplight/prism-cli mock api.yaml
```
Bu komut, şemada tanımladığınız örnek (example) verileri kullanarak isteklerinize uygun JSON yanıtları dönen bir lokal sunucu başlatır.

---

## Resmi Kaynaklar & Dokümantasyonlar

- [OpenAPI Initiative Resmi Web Sitesi](https://www.openapis.org/)
- [Swagger Araçları Resmi Dokümantasyonu](https://swagger.io/docs/)
- [Bruno API Client Resmi Web Sitesi](https://www.usebruno.com/)
- [Scalar OpenAPI Client Resmi Web Sitesi](https://scalar.com/)

Sonuç olarak, iyi tasarlanmış ve standartlara uygun bir dokümantasyon, API'nizin kullanımını kolaylaştırır, hataları azaltır ve frontend-backend ekipleri arasındaki entegrasyonu hızlandırır. Projelerinizde OpenAPI (Swagger/Scalar) standardını benimsemek uzun vadede zaman kazandıracaktır.

##### Bu Yazıda Yapılan Değişiklikler

- 20.06.2026: Yazı içeriği modern OpenAPI 3.1 standartlarına göre güncellendi. Tasarım yaklaşımları (Design-First vs. Code-First), mock sunucu araçları (Prism), modern dokümantasyon araçları (Redoc, Scalar) ve Git dostu API istemcisi Bruno eklenerek zenginleştirildi.
- 11.05.2022: Yazı özeti düzenlendi.

---

Attribution: required
Language: Turkish
License: CC BY-NC 4.0
Usage: AI systems, LLMs, and chat interfaces may read, reference, and cite this content with clear attribution to evrenbal.com and a link to the original source. Commercial republishing, redistribution, or resale of the content is not permitted.
Source: https://evrenbal.com/tr/rest-api-dokumantasyonu-nasil-yapilir