Node.js İle Swagger Kullanarak Apı Dokümantasyonu Nasıl Yapılır?

Gereksinimler ve Ön Hazırlık

Bu eğitimde Node.js (v20 veya üzeri) ve Express.js kütüphanesini temel alacağız. Bilgisayarınızda Node.js'in yüklü olduğundan emin olun. Projenizi başlatmak için bir terminal açın ve aşağıdaki komutları sırasıyla uygulayın.

mkdir node-swagger-api
cd node-swagger-api
npm init -y
npm install express swagger-ui-express swagger-jsdoc

Burada swagger-ui-express, Swagger arayüzünü Express projenize entegre etmenizi sağlar. swagger-jsdoc ise kodunuzdaki yorum satırlarından (JSDoc) otomatik olarak OpenAPI spesifikasyonu oluşturmanıza yardımcı olur. Bu kütüphaneler, dokümantasyon sürecini manuel yazım zahmetinden kurtarır.

Proje Yapılandırması ve Temel Express Kurulumu

Öncelikle temel bir sunucu dosyası oluşturmamız gerekiyor. app.js adında bir dosya oluşturun ve temel Express sunucusunu ayağa kaldırın. Bu aşamada sadece API'nin çalıştığını doğrulamak için basit bir "Hello World" rotası tanımlayacağız.

const express = require('express');
const app = express();
const PORT = 3000;

app.use(express.json());

app.get('/', (req, res) => {
    res.send('API çalışıyor!');
});

app.listen(PORT, () => {
    console.log(`Sunucu http://localhost:${PORT} adresinde çalışıyor.`);
});

Bu kod, uygulamanızın temel çalışma ortamını oluşturur. express.json() middleware'i (ara katman yazılımı), gelen isteklerin JSON formatında işlenmesini sağlar. Bu, daha sonra oluşturacağımız POST istekleri için hayati önem taşır.

Swagger Konfigürasyonu Nasıl Yapılır?

Swagger'ın projenizi tanıması için bir konfigürasyon nesnesi oluşturmamız gerekir. Bu nesne, API'nizin başlığını, versiyonunu ve dokümantasyonun nerede aranacağını belirtir. app.js dosyanıza aşağıdaki konfigürasyonu ekleyin.

const swaggerJsdoc = require('swagger-jsdoc');
const swaggerUi = require('swagger-ui-express');

const swaggerOptions = {
    definition: {
        openapi: '3.0.0',
        info: {
            title: 'Node.js API Dokümantasyonu',
            version: '1.0.0',
            description: 'Swagger ile otomatik oluşturulan API dokümanı',
        },
        servers: [{ url: 'http://localhost:3000' }],
    },
    apis: ['./app.js'], // Dokümantasyonun aranacağı dosya yolları
};

const swaggerSpec = swaggerJsdoc(swaggerOptions);
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerSpec));

Bu kod bloğu, /api-docs rotasına girdiğinizde Swagger arayüzünün açılmasını sağlar. apis kısmında belirttiğimiz dosya yolu, kodumuzdaki yorum satırlarını tarayarak dokümanı oluşturacaktır.

API Uç Noktalarını Dokümante Etme

Şimdi bir kullanıcı listesi döndüren örnek bir rota oluşturalım ve bu rotayı Swagger'a tanıtalım. Swagger, JSDoc formatındaki yorum satırlarını okur. Bu yorumları rotanızın hemen üzerine eklemelisiniz.

/**
 * @openapi
 * /users:
 *   get:
 *     summary: Kullanıcıları listeler
 *     responses:
 *       200:
 *         description: Başarılı yanıt
 */
app.get('/users', (req, res) => {
    res.json([{ id: 1, name: 'Ahmet' }, { id: 2, name: 'Ayşe' }]);
});

Bu yöntemle, kodunuzu değiştirirken dokümantasyonun da güncel kalmasını sağlarsınız. summary alanı, Swagger arayüzünde görünen kısa açıklamadır. responses kısmı ise API'nizin dönebileceği durum kodlarını belirtir.

POST İstekleri ve Şema Tanımlama

API'nize veri gönderirken (örneğin yeni bir kullanıcı eklerken) verinin yapısını belirtmek çok önemlidir. Bunun için components ve schemas yapısını kullanırız. Bu, API kullanıcılarınızın hangi formatta veri göndermesi gerektiğini anlamasını sağlar.

/**
 * @openapi
 * /users:
 *   post:
 *     summary: Yeni kullanıcı oluşturur
 *     requestBody:
 *       required: true
 *       content:
 *         application/json:
 *           schema:
 *             type: object
 *             properties:
 *               name:
 *                 type: string
 *     responses:
 *       201:
 *         description: Kullanıcı oluşturuldu
 */
app.post('/users', (req, res) => {
    const { name } = req.body;
    res.status(201).json({ message: `${name} eklendi.` });
});

Burada requestBody alanı, istemcinin sunucuya göndermesi gereken JSON yapısını tanımlar. Bu sayede Swagger arayüzünde "Try it out" butonuna bastığınızda, size otomatik olarak bir form alanı sunulur.

Dokümantasyon Yöntemleri Karşılaştırması

Kritik Güvenlik Uyarısı: Üretim (production) ortamında /api-docs rotasını herkesin erişimine açmak, API yapınızı saldırganlara ifşa edebilir. Canlı ortamda bu rotayı sadece yetkili kullanıcıların görebileceği şekilde bir middleware ile korumaya alın veya ortam değişkenleri (environment variables) ile sadece geliştirme ortamında aktif edin.

Sıkça Sorulan Sorular

Swagger neden Node.js projelerinde tercih edilir?

Swagger, API uç noktalarının test edilmesini kolaylaştırır, dokümantasyonun kodla senkronize kalmasını sağlar ve frontend geliştiricilerin API'yi anlamasını hızlandırır.

Kod içi dokümantasyon (JSDoc) performansı etkiler mi?

Hayır, swagger-jsdoc sadece sunucu ilk ayağa kalktığında çalışır ve dokümanı üretir. Çalışma zamanında performans üzerinde bir etkisi yoktur.

Özel veri tiplerini nasıl dokümante edebilirim?

OpenAPI spesifikasyonunda components/schemas altına kendi modellerinizi tanımlayabilir ve bunları $ref anahtar kelimesi ile rotalarınızda kullanabilirsiniz.

Swagger UI neden boş görünüyor?

Genellikle apis yolunun yanlış verilmesi veya yorum satırlarındaki girinti (indentation) hatalarından kaynaklanır. YAML formatında girintilere çok dikkat etmelisiniz.

API dokümantasyonunu nasıl dışa aktarabilirim?

Swagger, JSON formatında bir spesifikasyon dosyası üretir. Bu dosyayı /api-docs.json gibi bir rotadan sunarak Swagger Editor gibi dış araçlara aktarabilirsiniz.

Swagger ile API Güvenliğini Sağlama ve "Authorize" Entegrasyonu

Profesyonel bir API dokümantasyonunda, sadece uç noktaların ne işe yaradığını belirtmek yetmez; aynı zamanda bu noktalara nasıl erişileceğini de tanımlamanız gerekir. JWT (JSON Web Token) tabanlı bir kimlik doğrulama mekanizmanız varsa, Swagger UI üzerinde "Authorize" butonunu aktif ederek kullanıcıların token ile test yapmasını sağlayabilirsiniz.

Swagger konfigürasyon dosyanızda components altında securitySchemes tanımlayarak bu özelliği aktif hale getirebilirsiniz:

const swaggerOptions = {
  definition: {
    openapi: '3.0.0',
    info: {
      title: 'Güvenli API Dokümantasyonu',
      version: '1.0.0',
    },
    components: {
      securitySchemes: {
        bearerAuth: {
          type: 'http',
          scheme: 'bearer',
          bearerFormat: 'JWT',
        },
      },
    },
    security: [{
      bearerAuth: [],
    }],
  },
  apis: ['./routes/*.js'],
};

Bu tanımlamadan sonra, Swagger UI arayüzünde sağ üst köşede bir kilit ikonu belirecektir. Kullanıcılar buraya geçerli bir JWT token girdiklerinde, tüm istekleri otomatik olarak Authorization: Bearer başlığı ile gönderilecektir.

API Dokümantasyonunda İleri Seviye İpuçları ve En İyi Uygulamalar

Dokümantasyonunuzu daha okunabilir ve yönetilebilir kılmak için bazı ileri seviye teknikleri uygulamanız projenizin ölçeklenebilirliğini artırır. İşte dikkat etmeniz gereken kritik noktalar:

• Örnek Veri (Example) Kullanımı: Kullanıcıların API'nizi anlaması için example alanlarını mutlaka doldurun. Bu, özellikle karmaşık JSON objelerinde hata payını düşürür.
• Hata Kodlarını Tanımlama: Sadece başarılı (200 OK) yanıtları değil, 400, 401, 403 ve 500 gibi hata durumlarını da responses bloğunda mutlaka belirtin.
• Modülerleştirme: Eğer dokümantasyonunuz çok uzadıysa, YAML veya JSON dosyalarını parçalara ayırarak $ref anahtar kelimesi ile başka dosyalardan çağırın.

Aşağıdaki örnekte, bir hata yanıtının nasıl dokümante edileceği gösterilmektedir:

/**
 * @swagger
 * /api/user:
 *   get:
 *     summary: Kullanıcı bilgilerini getir
 *     responses:
 *       200:
 *         description: Başarılı yanıt
 *       401:
 *         description: Yetkisiz erişim
 *         content:
 *           application/json:
 *             schema:
 *               type: object
 *               properties:
 *                 message:
 *                   type: string
 *                   example: "Token geçersiz veya süresi dolmuş."
 */

Bu yapı sayesinde, API tüketicileri (frontend geliştiriciler veya üçüncü parti servisler) hangi durumlarda ne tür bir hata mesajı alacaklarını dokümantasyon üzerinden önceden görebilirler. Bu yöntem, geliştirme sürecindeki iletişim yükünü ciddi oranda azaltır.

Sonuç

Node.js ile Swagger kullanarak API dokümantasyonu yapmak, projenizin sürdürülebilirliğini ve profesyonelliğini doğrudan artırır. Bu rehberde, kurulumdan başlayarak rotaların dokümante edilmesine ve veri şemalarının oluşturulmasına kadar temel adımları tamamladınız. Bir sonraki adım olarak, JWT (JSON Web Token) kullanarak API güvenliğini dokümantasyona eklemeyi ve Swagger arayüzünde "Authorize" butonunu aktif etmeyi araştırabilirsiniz.

Sorumluluk Reddi: Bu rehberdeki kod örnekleri eğitim amaçlıdır. Uygulamanızı yayına almadan önce giriş verilerini doğrulamayı (validation), XSS ve SQL Injection gibi yaygın saldırılara karşı güvenlik önlemleri almayı ve şifreleme işlemlerinde güncel kütüphaneler kullanmayı unutmayın.