Web API geliştirirken API de yazılan metodların ne iş yaptığı? Hangi parametreleri aldığı? Ne cevap döndüğü? Gibi bilgilerin yer aldığı dökümanlar hazırlanması gerekir. Çünkü o API ile, uygulamasını haberleştiren yazılımcı, nasıl bir veri alıp göndereceğini bilmesi gerekir. İşte bu noktada Swagger UI devreye girmektedir.
Swagger UI, OpenAPI (Swagger) spesifikasyonu ile tanımlanan bir API için, dökümantasyonları görsel olarak oluşturan açık kaynaklı bir projedir. Swagger UI, GitHub’tan indirip kullanılabilirsiniz.
Swagger UI API’lere arayüz görevi görmektedir. Yazılımcıların nasıl bir entegrasyon yapacağını görmelerini sağlar. Swagger UI arayüzünü oluştururken verileri “swagger.json” dan okur. Eğer API’nizi Node.js ile yazıyorsanız maalesef “swagger.json” dosyasını kendiniz hazırlamanız gerekiyor(en son öyleydi yeni bir araç çıkmadıysa). Aşağıdaki örnek gibi.
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 | {
"swagger": "2.0",
"info": {
"version": "1.0.0",
"title": "İsmail KAŞAN-NodeJS-Api-MongoDB",
"description": "A minimal and easy to follow example of what you need to create a CRUD style API in NodeJs",
"license": {
"name": "MIT",
"url": "https://opensource.org/licenses/MIT"
}
},
"tags": [
{
"name": "Todos",
"description": "API for todos in the Personel List"
}
],
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"paths": {
"/todos": {
"get": {
"tags": [
"Todos"
],
"summary": "Get all todos",
"responses": {
"200": {
"description": "OK",
"schema": {
"$ref": "#/definitions/TodoList"
}
}
}
},
"post": {
"tags": [
"Todos"
],
"summary": "Create a new todo",
"produces": [
"application/json"
],
"parameters": [
{
"name": "model",
"in": "body",
"description": "todo detail",
"required": true,
"schema": {
"$ref": "#/definitions/Todo"
}
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"$ref": "#/definitions/Todo"
}
},
"400": {
"description": "Failed. Bad post data."
}
}
}
}
"definitions": {
"TodoList": {
"type": "object",
"properties": {
"_id": {
"type": "string"
},
"title": {
"type": "string"
},
"date": {
"type": "string"
},
"completed": {
"type": "string"
}
}
},
"Todo": {
"type": "object",
"properties": {
"title": {
"type": "string"
},
"date": {
"type": "string"
},
"completed": {
"type": "string"
}
}
}
}
}
|
.Net Core tarafında ise işler biraz daha kolaylaştırılmış. “Swashbuckle.AspNetCore” Nuget paketi ile gelen dll’ler sizin için işi kolaylaştırıyor. Metodlarınızın ve Class’larınızın üzerine yazdığınız Summary’leri alıp “swagger.json”dosyasını sizin için otomatik oluşturuyor.
Projemize Swagger UI eklemek için aşağıdaki komut ile Nuget üzerinden ilgili kütüphaneyi ekliyoruz.
1 | dotnet add package Swashbuckle.AspNetCore
|
Paketi indirdikten sonra ilgili ayarlar için, Startup.cs dosyasında aşağıdaki eklemeleri yapmamız gerekiyor.
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 | // Add in ConfigureServices Method services.AddSwaggerGen(c => { c.SwaggerDoc("v1", new OpenApiInfo { Title = "Net Core Example Api", Version = "v1" }); c.AddSecurityDefinition("Bearer", new OpenApiSecurityScheme { Description = @"JWT Authorization header using the Bearer scheme. \r\n\r\n Enter 'Bearer' [space] and then your token in the text input below. \r\n\r\nExample: 'Bearer 12345abcdef'", Name = "Authorization", In = ParameterLocation.Header, Type = SecuritySchemeType.ApiKey, Scheme = "Bearer" }); c.AddSecurityRequirement(new OpenApiSecurityRequirement() { { new OpenApiSecurityScheme { Reference = new OpenApiReference { Type = ReferenceType.SecurityScheme, Id = "Bearer" }, Scheme = "oauth2", Name = "Bearer", In = ParameterLocation.Header, }, new List<string>() } }); }); // Add in Configure Method app.UseSwagger(); app.UseSwaggerUI(c => c.SwaggerEndpoint("/swagger/v1/swagger.json", "ResponseCache v1")); |
AddSecurityDefinition ve AddSecurityRequirement metodlarını sistemdeki yetkilendirme yapısında, arayüz üzerinden atılan isteklerde token bilgisinin eklenebilmesi için ayar yapıyoruz.
Sistemde yetkilendirme yok ise 5. satırdaki kod yeterli olacaktır. Configure Metodunda middleware’e Swagger UI eklemeyi unutmuyoruz.
1 2 | app.UseSwagger(); app.UseSwaggerUI(c => c.SwaggerEndpoint("/swagger/v1/swagger.json", "NetCoreExampleApi v1")); |
Kurulum ve ayarlama işlemi bu kadar basit. Artık projeyi çalıştırabiliriz. Projeyi çalıştırıdığımızda tarayıcıda böyle bir ekran karşılıyor bizi.
 |
| Metodların türleri(Get,Post vs.) ile url yapıları renkli bir görsel ile çok güzel bir şekilde gösterilmiş. Class’ların şema yapısı da mevcut. Authorize butonuna tıklandığında token eklemek için bir pop-up açılacaktır. |
 |
| Swagger UI üzerinden yapılan isteklerin Authorization Header’ına token eklemek için açılan pop-up. |
Bu arayüz üzerinden ilgili methodlar test edilebilir. Apinin fonksiyonlarına veri gönderebilir ve veri çekebilirsiniz. Postman gibi programlara gerek kalmadan yazdığınız API’yi hızlıca test edebilirsiniz.
Bazen gözden kaçan ufak tefek durumlarda, Swagger UI sistemdeki dinamik oluşan “swagger.json” dosyasını okuyamaz.Bu hata aşağıdaki gibidir.
Bu hatanın sebep olduğu olayı şu şekilde açıklayabiliriz. Aynı Controller içinde bulunan farklı iki metodun aynı Http metodu ile işratelenmesidir. Aşağıdaki örnekte iki metod da [HttpGet] atribütü ile işaretlenmiş. Dolayısıyla swagger.json dosyasında yanı route sahip 2 farklı metod olduğu için hata vermektedir.
 |
| [HttpGet] ile işaretlenmiş metodlar |
Eğer Controller içinde 2 den fazla Http metod attribütü ile işaretlenmiş metod varsa,bunların url bilgilerini [Route(“”)] atribütü ile belirtmemiz gerekir. Yoksa Swagger UI url yapısına karar veremiyor. Aşağıdaki gibi olması gerekiyor.
 |
| [HttpGet] ve [Route(“”)] atribütleri ile işaretlenmiş metodlar |
Elimden geldiğinde anlatmaya çalıştım. Umarım faydalı bir içerik olmuştur.
Yararlanılan kaynaklar;
Örnek Proje kodları buradan indirilebilir.
