API geliştirme sürecinde, API belgelerini anlaşılır ve erişilebilir hale getirmek, API’leri test etmek ve kullanmak için önemlidir. İşte tam da burada Swagger UI devreye giriyor. Swagger UI, API belgelerini etkileşimli bir şekilde görüntüleme ve test etme aracı olarak biz geliştiricilere kolaylık sağlar. Bu yazı içeriğinde Swagger UI’nın ne olduğunu ve neden bu kadar önemli olduğunu keşfedeceğiz.

Aynı zamanda NodeJS ile birlikte bir Swagger UI örneği oluşturacağız. DB olarak ise önceki yazımız olan JSON Server Nedir ve Nasıl Kullanılır? içeriğinde bahsedilen JSON-Server’dan faydalanacağız.

Swagger UI Nedir?

Swagger UI, Swagger belgelerini kullanarak API rotalarını, parametreleri, yanıtları ve hata durumlarını etkileşimli bir şekilde görsel olarak sunan bir arayüzdür. API belgelerini daha anlaşılır ve erişilebilir hale getirirken, API test sürecini de basitleştirir. API belgelerini YAML veya JSON formatında oluşturabilir ve Swagger UI ile etkileşimli olarak görüntüleyebiliriz.

Swagger UI’nın Sunduğu Özellikleri

1. Görsel Olarak API Belgelerini Görüntüleme

Swagger UI, API belgelerini sıkıcı metinler yerine görsel bir şekilde sunarak biz geliştiricilerin belgelere daha hızlı ve etkili bir şekilde erişmemizi sağlar. API rotaları, parametreler, yanıtlar ve hata durumları gibi bilgileri açıklayıcı bir şekilde görüntüleyerek belgelerin anlaşılabilirliğini artırır.

2. Etkileşimli Testler ile API’leri Deneme

Swagger UI, API’leri test etmek için etkileşimli bir ortam sağlar. Swagger UI üzerinde, kullanıcı dostu bir arayüz aracılığıyla örnek istekler oluşturabilir ve gerçek yanıtları anında görüntüleyebiliriz. Bu özellik, API’lerin doğru çalıştığından emin olmamızı sağlayarak hata ayıklama sürecini kolaylaştırır.

3. Otomatik Tamamlama ve Parametre Doğrulama

Swagger UI, bizlere otomatik tamamlama ve parametre doğrulama özellikleri sunar. API çağrılarında kullanılması gereken parametreleri geliştiricilere hatırlatır ve doğru bir şekilde doldurulmasını sağlar. Bu özellikler, hatalı API çağrılarını azaltır ve bize zaman kazandırır.

4. API Belgelerini Gezinme ve Arama

Swagger UI, API belgelerini kolayca gezinmemizi ve arama yapmamızı sağlar. Belge içinde hızlı bir şekilde istediğimiz rotalara, parametrelere veya örnek isteklere ulaşabiliriz. Bu özellik, belge büyüdükçe kaybolmadan bilgilere erişebilmemizi sağlar ve belge geliştirme sürecini hızlandırır.

Bu şekilde Swagger UI, API belgelerini daha erişilebilir, etkileşimli ve kullanıcı dostu hale getirirken, biz geliştiricilere API’leri test etme ve belgeleme sürecinde yardımcı olur.

Node.js ile Swagger UI Örneği

Şimdi sizlerle Node.js kullanarak basit bir proje yazacağız ve Swagger UI’ın basit kullanımına dair içeriği incelemiş olacağız. Bu içerik Swagger UI ile ilgili olduğu için kodlarla alakalı açıklama yapmacağım.

Bu projemiz “Get, Add, Delete” metodlarını içerecek şekilde geliştirilecek ve Swagger UI üzerinde bu metodlarla işlemler yapılabilecek.

1. Projeyi Oluşturma Ve Gerekli Paketleri Kurma

Boş bir klasör oluşturalım ve terminal üzerinde bu klasör yolunda aşağıdaki komutu çalıştırarak package.json dosyamızın oluşturulmasını sağlayalım.

1
npm init -y

Ardından projemizde kullanacağımız express, swagger, json-server gibi paketleri yüklemek için şu komutu çalıştıralım.

1
npm install express swagger-ui-express json-server --save

2. JSON Veritabanı Oluşturma

Projemizde Swagger UI üzerinde gerçekleştireceğimiz “Get, Add, Delete” işlemleri için kullanacağımız bir veritabanı yapısını JSON-Server kullanarak oluşturacağız. Bunun için klasörümüzde “db.json” adında bir dosya oluşturalım. Başlangıç için değer veri atamasını yapabiliriz.

1
2
3
4
5
6
{
"users": [
{ "id": 1, "name": "John Doe", "email": "john@example.com" },
{ "id": 2, "name": "Jane Doe", "email": "jane@example.com" }
]
}

Oluşturduğumuz db.json dosyası üzerinde “users” koleksiyonunda bazı kullanıcı verilerini tutacağız ve bunlar üzerinde işlem yapacağız.

3. Swagger JSON Dosyasını Oluşturma

Swagger UI örneği için kritik olan dosyalardan birisi budur. Burada üzerinde işlem yapacağımız path ve metodları ayrı ayrı tanımlamamız gerekir. Bu tanımlama esnasında metodun alacağı parametre ve cevap olarak döneceği tipler hakkında da tanımlamaları burada yapacağız.

Projemize uygun olan swagger.json dosyasını aşağıda ki gibi oluşturabilirsiniz.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
{
"swagger": "2.0",
"info": {
"version": "1.0.0",
"title": "MySimple Node.js API",
"description": "Bu Swagger UI hakkında örnek API'dir"
},
"host": "localhost:3000",
"basePath": "/api",
"schemes": [
"http"
],
"paths": {
"/users": {
"get": {
"summary": "Tüm kullanıcıları getirir",
"responses": {
"200": {
"description": "Başarılı yanıt",
"schema": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": { "type": "integer" },
"name": { "type": "string" },
"email": { "type": "string" }
}
}
}
}
}
},
"post": {
"summary": "Yeni bir kullanıcı ekler",
"parameters": [
{
"name": "user",
"in": "body",
"description": "Eklenen kullanıcı bilgileri",
"schema": {
"type": "object",
"properties": {
"id": { "type": "integer" },
"name": { "type": "string" },
"email": { "type": "string" }
},
"required": ["id", "name", "email"]
}
}
],
"responses": {
"200": {
"description": "Başarılı yanıt",
"schema": {
"type": "object",
"properties": {
"id": { "type": "integer" },
"name": { "type": "string" },
"email": { "type": "string" }
}
}
}
}
}
},
"/users/{id}": {
"get": {
"summary": "Belirtilen ID'ye sahip kullanıcıyı getirir",
"parameters": [
{
"name": "id",
"in": "path",
"description": "Kullanıcının ID'si",
"required": true,
"type": "integer"
}
],
"responses": {
"200": {
"description": "Başarılı yanıt",
"schema": {
"type": "object",
"properties": {
"id": { "type": "integer" },
"name": { "type": "string" },
"email": { "type": "string" }
}
}
},
"400": {
"description": "Geçersiz istek"
},
"404": {
"description": "Kullanıcı bulunamadı"
}
}
},
"delete": {
"summary": "Belirtilen kullanıcıyı siler",
"parameters": [
{
"name": "id",
"in": "path",
"description": "Silinecek kullanıcının ID'si",
"required": true,
"type": "integer"
}
],
"responses": {
"200": {
"description": "Başarılı yanıt"
},
"400": {
"description": "Geçersiz istek"
},
"404": {
"description": "Kullanıcı bulunamadı"
}
}
}
}
}
}

Burada swagger.json içeriğine biraz değinmemiz gerekebilir. Yukarıdaki dosya içeriğini incelediğiniz de gözünüze bazı tanımlamar doğrudan çarpacaktır.

  • “swagger” anahtarı, kullanılan Swagger sürümünü belirtir.
  • “info” anahtarı, API hakkında temel bilgileri içerir, örneğin versiyon, başlık ve açıklama bunlardır.
  • “host” anahtarı, API’nin barındırıldığı sunucunun adını ve port numarasını belirtir.
  • “basePath” anahtarı, API’nin root yolunu belirtir.
  • “schemes” anahtarı, API’ye erişmek için kullanılabilecek protokollerin listesini içerir. Bu örrnekte biz sadece “http” kullanacağımızı belirttik..
  • “paths” anahtarı, API’nin üzerinde istekte bulunabileceğimiz yollarını ve bu yollar üzerinde gerçekleştirilebilecek işlemleri içerir. Örneğin bu örnekte yalnızca, “/users” ve “/users/{id}” yolları mevcuttur.

4. Express İle Uygulama Oluşturma

Database ve Swagger UI yapıları için gerekli tanımlamaları yaptıktan sonra aslında geriye tek bir adım kaldı. Bu da projemizde çalıştıracağımız metodları yazmak. Bunun için projemizde index.js adında bir dosya oluşturmamız gerekiyor.

Dosya içeriğini ise aşağıda ki şekilde sağladığımızda Swagger UI ile birlikte tam bir çalışma içerisinde olacaklardır.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
const express = require('express');
const swaggerUi = require('swagger-ui-express');
const swaggerDocument = require('./swagger.json');
const jsonServer = require('json-server');

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

app.use(express.json());
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument));

const router = jsonServer.router('db.json');
app.use('/api', router);

app.get('/api/users', (req, res) => {
const users = router.db.get('users').value();
res.json(users);
});

app.post('/api/users', (req, res) => {
const { id, name, email } = req.body;
if (!id || !name || !email) {
return res.status(400).json({ error: 'Bazı alanlar eksik.' });
}
const newUser = { id, name, email };
router.db.get('users').push(newUser).write();
res.json(newUser);
});

app.get('/api/users/:id', (req, res) => {
const { id } = req.params;
const user = router.db.get('users').find({ id: parseInt(id) }).value();
if (!user) {
return res.status(404).json({ error: 'Kullanıcı bulunamadı.' });
}
res.json(user);
});

app.delete('/api/users/:id', (req, res) => {
const { id } = req.params;
const userIndex = router.db.get('users').findIndex({ id: parseInt(id) }).value();
if (userIndex === -1) {
return res.status(404).json({ error: 'Kullanıcı bulunamadı.' });
}
router.db.get('users').splice(userIndex, 1).write();
res.sendStatus(200);
});

app.listen(PORT, () => {
console.log(`Server başlatıldı. Port: ${PORT}`);
});

5. Projeyi Çalıştırma

Terminal üzerinde proje klasörüne erişip aşağıda ki komutu çalıştırarak projenin çalışmasını sağlayabiliriz.

1
node index.js

Bu komutla birlikte yazdığımız node uygulaması çalışmaya başlayacak ve http://localhost:3000/api-docs adresi üzerinden aşağıdaki görselde ki Swagger arayüzüne erişebilir olacağız.

Projeye Github Üzerinden Erişim

Projeye ait kodları indirmek ve incelemek isterseniz Node.js Swagger UI Example adresi üzerinden Github reposuna ulaşabilirsiniz.

Sonuç

Swagger UI, API belgelerini etkileşimli bir şekilde görüntüleme ve test etme konusunda bizlere büyük kolaylık sağlayan güçlü bir araçtır. API projelerimizde Swagger UI kullanarak geliştirici deneyimini iyileştirebiliriz ve hataları hızlıca tespit edebiliriz. Swagger UI, API geliştirme sürecinizde size yardımcı olacak önemli bir araçtır.

Faydalı olması dileğiyle.