Swagger UI 101 🎯

Merhabalar, bu yazımda Swagger UI’ın genel bir anlatımını ve Swagger UI’da nasıl test yapılacağını kısaca anlatmaya çalıştım.

Keyifli okumalar dilerim.🚀

Konu Başlıkları:

⛳ Swagger UI Nedir?

⛳ Swagger UI’ın Özellikleri

⛳ Swagger UI İçerisinde Kullanılan Methodlar

⛳Swagger UI Nasıl Çalışır?

⛳Swagger UI ‘da Test Nasıl Yapılır?

⛳ Swagger UI Nedir?

Swagger UI, geliştirilen API’lerin görselleştirilmesine ve otomatik dökümantasyon oluşturmasına yardımcı olan bir arayüzdür.

OpenAPI Specification (OAS) formatında API’leri tanımlamak için yaygın olarak kullanılan bir dizi araç sunar.

Web API projelerinde bulunan kaynakları ve bu kaynaklarla ilişkilendirilen işlemleri anlamamızı sağlar. Böylece, ekip içindeki ve API’yi kullanacak diğer geliştiricilerin, API’nin nasıl çalıştığı ve ne tür işlemleri desteklediği konusunda bilgi sahibi olmasını sağlar.

⛳ Swagger UI’ın özellikleri

🏆Görselleştirme: API’leri görsel olarak temsil ederek, kaynakların ve bunlarla ilişkili işlemlerin anlaşılmasını kolaylaştırır.

🏆Otomatik Dökümantasyon: API’lerde bulunan kaynakları ve bu kaynaklarla yapılabilecek işlemleri otomatik olarak belgelendirir.

🏆Kolay Paylaşım: Kolayca paylaşmayı sayesinde ekip içindeki diğer üyelerle bilgi paylaşmayı ve dış geliştiricilere API hakkında bilgi verme sürecini kolaylaştırır.

🏆Test Edilebilirlik: Kullanıcılar, arayüz üzerinden API’lerle etkileşime geçebilir ve işlevselliği test edebilir, bu da hata ayıklama sürecini hızlandırır.

⛳ Swagger UI içerisinde Kullanılan Methodlar:

🪐GET: GET metodu, bir kaynağın mevcut durumunu almak için kullanılır.

Payload: Payload, genellikle bu durumun bir temsili olan JSON veya XML formatında olabilir.

• Not* GET API’sinde payload olabilir ancak standart uygulama değildir ve genellikle tavsiye edilmez. GET istekleri, kaynaklardan veri almak için kullanılır.
• Parametre olarak apinin içerisinde hangi veri isteniyorsa gönderilebilir. (Query Parameters). Örneğin Bu apide id=123 olan apiye call atılmış ve sonucunda bu usera ait bilgiler responseda görüntülenmiştir.
• *Not* Query Parameters : API isteklerinde URL parametreleri veya query string içindeki parametreler kullanılarak filtreleme yapılabilir. Örneğin: GET /api/users?role=admin&status=active
• User id parametre olarak gönderilmiş bir GET apisi:

GET /api/users?id=123 HTTP/1.1
Host: example.com
Authorization: Bearer your_token_here

Payload = Request Body

Response: İstemcinin istediği kaynağın mevcut durumunu içerir.

Responses

GET /api/users?id=123 api response;

🪐POST: POST metodu, yeni bir kaynak oluşturmak veya mevcut bir kaynağı güncellemek için kullanılır.

Payload: POST isteği sırasında gönderilen verilerin bir temsili olan bir payload (veri) da içerebilir.

Örnek bir kullanıcı oluşturma payloadu:

POST /api/users HTTP/1.1
Host: example.com
Content-Type: application/json
Authorization: Bearer your_token_here

{
    "username": "elifguncan",
    "email": "elif.guncan@example.com",
    "password": "securepassword123",
    "firstName": "Elif",
    "lastName": "Güncan"
}

Response: POST isteğinin bir sonucu olarak, genellikle bir HTTP response (yanıt) alınır. Bu yanıt, oluşturulan veya güncellenen kaynağın durumunu veya bir işlem durumunu içerebilir.

Örnek bir response:

{
    "id": 123,
    "username": "elifguncan",
    "email": "elif.guncan@example.com",
    "firstName": "Elif",
    "lastName": "Güncan",
    "createdAt": "2024-06-24T12:34:56Z",
    "updatedAt": "2024-06-24T12:34:56Z"
}

🪐PUT: PUT metodu, var olan bir kaynağın tamamen değiştirilmesi veya güncellenmesi için kullanılır.

Payload: PUT isteği, güncellenen kaynağın tam bir temsilini içeren bir payload ile birlikte gönderilir.

PUT /api/users/123 HTTP/1.1
Host: example.com
Content-Type: application/json
Authorization: Bearer your_token_here

{
    "username": "elifguncan",
    "email": "elif.guncan@example.com",
    "password": "newsecurepassword123",
    "firstName": "Elif",
    "lastName": "Güncan"
}

Response: PUT isteğinin sonucunda genellikle bir HTTP response (yanıt) alınır. Bu yanıt, güncellenen kaynağın durumunu veya bir işlem durumunu içerebilir.

{
    "id": 123,
    "username": "elifguncan",
    "email": "elif.guncan@example.com",
    "firstName": "Elif",
    "lastName": "Güncan",
    "createdAt": "2024-06-24T12:34:56Z",
    "updatedAt": "2024-06-24T12:45:00Z"
}

🪐PATCH: PATCH metodu, var olan bir kaynağın kısmen güncellenmesi için kullanılır.

Payload: PATCH isteği, güncellenen alanların ve değerlerin bir temsili olan bir payload ile birlikte gönderilir.

Payload ile e-mail ve lastname güncellenmesi için apiye call atılır.

PATCH /api/users/123 HTTP/1.1
Host: example.com
Content-Type: application/json
Authorization: Bearer your_token_here

{
    "email": "elif.new@example.com",
    "lastName": "Yeni"
}

Response: PATCH isteğinin sonucunda da genellikle bir HTTP response (yanıt) alınır. Yanıt, güncellenen kaynağın durumunu veya bir işlem durumunu içerebilir.

{
    "id": 123,
    "username": "elifguncan",
    "email": "elif.new@example.com",
    "firstName": "Elif",
    "lastName": "Yeni",
    "createdAt": "2024-06-24T12:34:56Z",
    "updatedAt": "2024-06-24T13:00:00Z"
}

🪐DELETE: DELETE metodu, var olan bir kaynağın silinmesi için kullanılır.

Payload: DELETE isteğinde genellikle bir payload bulunmaz veya payload boş olabilir.

Parametre olarak id gönderilebilir.

DELETE /api/users?id=123 HTTP/1.1
Host: example.com
Authorization: Bearer your_token_here

Response: DELETE isteğinin sonucunda genellikle bir HTTP response (yanıt) alınır. Bu yanıt, silinen kaynağın durumunu veya bir işlem durumunu içerebilir.

HTTP/1.1 204 No Content

⛳Swagger UI Nasıl Çalışır?

• Swagger UI, belirli bir URL’den sağlanan OpenAPI Specification (OAS) belgelerini kullanarak çalışır.
• Bir API’nin Swagger UI ile kullanılabilir hale gelmesi için, API’nin OpenAPI Specification formatında (JSON veya YAML olarak) bir belgesinin olması gerekir.
• Swagger UI, bu belgeyi okur ve kullanıcıya API’nin dokümantasyonunu görsel bir şekilde sunar.

⛳Swagger UI ‘da Test Nasıl Yapılır?

Örnek Bir user oluşturma apisi ile başlayalım. Bu apiler örnek apiler olduğu için authorization bulunmadığından authorize işlemi yapılmadı.

SwaggerUI’da apilerin uygunluklarını kullanmak için token türlerinden biri ile authorize olunması gerekmektedir.

Swagger ile yetkilendirme işlemleri, API’nin güvenlik gereksinimlerine bağlı olarak farklı yöntemlerle gerçekleştirilebilir. Bu yöntemler;

1. Bearer Token ile Yetkilendirme:

• Bearer token, JWT (JSON Web Token) gibi güvenlik belirteçleri kullanılarak API’ye erişim sağlamak için yaygın bir yöntemdir.
• Swagger UI’da, bu tür yetkilendirme genellikle “Authorize” düğmesi kullanılarak yapılır.

2. API Key ile Yetkilendirme:

• Bazı API’ler, belirli bir anahtar (API Key) kullanarak yetkilendirme yapar.
• Swagger UI’da, bu anahtar genellikle sorgu parametresi, başlık veya gövde içinde iletilir.

3. Temel Kimlik Doğrulama (Basic Auth):

• Kullanıcı adı ve parola ile temel kimlik doğrulama sağlanabilir.
• Swagger UI’da, kullanıcı adı ve parola girilerek yetkilendirme yapılır.

4. OAuth2 ile Yetkilendirme:

• OAuth2, daha gelişmiş ve güvenli bir yetkilendirme protokolüdür.
• Swagger UI, OAuth2 akışlarını destekler ve bu akışlar üzerinden yetkilendirme yapılabilir.

Token türleri:

Swagger, token türlerini doğrudan tanımlamaz. Swagger, OAuth 2.0 gibi yetkilendirme protokollerini ve genellikle API belgelerinde bu tür yetkilendirme protokollerini belirtirken kullanılır.

OAuth 2.0'nin tanımladığı token türleri:

1. Access Token: Bir kullanıcının kimliğini doğrulamak için kullanılan ve API’ye erişim sağlayan bir türdür.
2. Refresh Token: Kullanıcının erişim token’ının yenilenmesine izin veren ve uzun vadeli erişim için kullanılan bir türdür.
3. Authorization Code: Kullanıcının erişim token’ını almak için kullanılan bir kod türüdür. Genellikle OAuth 2.0'nin ‘authorization code’ akışında kullanılır.
4. Client Credentials: Bir uygulamanın kendi adına API’ye erişmek için kullanılan bir türdür. Genellikle güvenli ve güvenilir bir uygulama kimliği (client ID) ve sırrı (client secret) kullanılarak sağlanır.

TEST -> Örnek Bir user oluşturma apisi

User Oluşturma işlemi POST/user apisi ile yapılır.

İşlem Yapılmak istenen api’ye tıklanır. Try it out butonuna basılır.

Açılan ekranda Request Body Bilgileri doldurulur ve Execute butonuna tıklanır.

POST/user/{username}

Apinin response’u 201 olarak başarılı bir şekilde oluşturulduğunu gösterir.

GET GET/user/{username} apisi ile daha önce oluşturulan kullanıcılar username’e göre getirilir. Örneğin,

GET/user/{username}

PUT/user/{username} api yardımı ile username apisiyle oluşturulan alanların herhangi bir yerinde update işlemi yapılabilir. Bu apiyi kullanabilmek için parametre olarak username yazılması zorunludur.

PUT/user/{username}

DELETE/user/{username} türündeki api’ye username parametre olarak gönderilir ve silme işlemi gerçekleştirilir.

DELETE/user/{username}

✨Swagger 101 yazımı okuduğunuz için teşekkür ederim. Umarım bu yazı, Swagger’ın temellerini anlamanıza yardımcı olmuştur. Swagger’ı kullanarak API belgelerinizi oluşturmak ve yönetmek konusunda daha fazla bilgi edinmek için aşağıdaki kaynaklara bakabilirsiniz. Başarılar dilerim!

SwaggerHub Explore

Swagger