Spec Tasarım Editörü

Spec Tasarım Editörü Kavramı

Spec Tasarım Editörü, API Designer'ın spec first yaklaşımında OpenAPI/Swagger spesifikasyonu oluşturma, düzenleme ve yönetme için kullanılan ana araçtır. Formlar üzerinden veri girişi yaparak yeni API Tanım Belgeleri (API Spec) oluşturur, var olan API Tanım Belgelerini içe aktarır ve günceller. OpenAPI 3.0.x ve OpenAPI 2.x (Swagger) standartlarını destekler.

Spec First Yaklaşımı

OpenAPI/Swagger spesifikasyonu önce oluşturulur

API tasarımı spesifikasyon ile başlar.

Form Tabanlı Düzenleme

Formlar üzerinden veri girişi yapılır

Kod yazmadan API Spec oluşturma ve düzenleme.

İçe Aktarma Desteği

Var olan API Spec'ler içe aktarılabilir

OpenAPI 3.0.x ve Swagger 2.x desteği.

API Proxy Oluşturma

Spesifikasyondan API Proxy oluşturulur

API Spec'ten otomatik API Proxy oluşturma.

bilgi

API Spec Editörü üzerinden girilen bilgilerin detaylı açıklaması için OpenAPI Spesifikasyonu adresine bakabilirsiniz.

Spec Tasarım Editörü Özellikleri

OpenAPI/Swagger Spesifikasyonu

Spec first yaklaşımında OpenAPI/Swagger spesifikasyonu oluşturma ve düzenleme:

API Spec Oluşturma

• Boş API Spec oluşturma
• Var olan Spec'i içe aktarma
• URL veya dosya yükleme
• Spec authorization desteği

Endpoint ve İşlem Tasarımı

• Path (adres) tanımlama
• HTTP method belirleme
• Operation (işlem) yönetimi
• Parametre tanımları

Veri Modeli Yönetimi

• Veri modeli oluşturma
• Ortak veri modellerini içe aktarma
• Schema tasarımı
• Property yönetimi

API Spec Yönetimi

API Tanım Belgelerinin oluşturulması ve yönetimi:

Spec Oluşturma

Yeni API Spec oluşturulur

• Boş API oluşturma
• Var olan Spec'i içe aktarma
• Form tabanlı düzenleme

Spec Düzenleme

API Spec'ler düzenlenir ve güncellenir

• Genel bakış yönetimi
• Endpoint ve işlem tanımları
• Veri modeli yönetimi

API Proxy Oluşturma

Spec'ten API Proxy oluşturulur

• Otomatik API Proxy oluşturma
• Şablon olarak Spec kullanımı
• Birden çok API Proxy oluşturma

API Tanım Belgesi Listesi

Ana menüden Spec Tasarım Editörü bağlantısına tıklandığında API Tanım Belgesi Listesi görüntülenir.

Listenin üst kısmında filtre alanları bulunur. Filtre alanları güncellendiği zaman liste içeriği de filtreye uygun olarak güncellenir.

API Tanım Belgesi Oluşturma

Var olmayan bir API'nin tasarlanması ya da code-first yaklaşımla geliştirilmiş ve herhangi bir tanım belgesi olmayan API'lerin dokümantasyonunu oluşturmak amacıyla kullanılır.

Liste arayüzünün sağ üst kısmındaki + Yeni (Create) tuşuna tıklanarak yeni bir API Tanım Belgesi oluşturulabilir.

Yeni API Tanım Belgesi oluşturulurken iki seçenek bulunmaktadır.

Form Doldurarak API Tanım Belgesi Oluşturma

Yeni API Tanım Belgesi arayüzü açıldığında, var olan iki seçenekten Boş API (Blank API) seçeneğinin varsayılan olarak seçili geldiği görülür.

Yeni API Tanım Belgesi arayüzü için kullanılan alanlar aşağıdaki tabloda görülmektedir.

Alan	Açıklama
Başlık (Title)	API Tanım Dosyasının listede görünen başlığı/adıdır. Zorunludur ve proje bazında biricik (unique) olmalıdır.
Açıklama	API Tanım Dosyasına ilişkin açıklamadır. Girilmesi isteğe bağlıdır.
Sunucular (Servers)	API'nin hizmet verdiği/vereceği sunucuların listesidir.
Sunucu - URL	API'ye erişilebilecek adrestir. Zorunludur.
Sunucu - Açıklama	Bu sunucuya ilişkin açıklamadır. Girilmesi isteğe bağlıdır.

Başlık (Title) alanı doldurulup Sunucular (Servers) bölümünde en az bir sunucu kaydı oluşturduktan sonra sağ üstteki Oluştur (Create) tuşu tıklanabilir hale gelir ve bu tuşa basılarak tanım dosyası kaydedilebilir. Tanım dosyası kaydedildikten sonra yapılabilecek işlemler API Tanım Belgesi Güncelleme kısmında açıklanmıştır.

Var olan API Tanım Belgesini İçe Aktarma

Yeni API Tanım Belgesi oluşturmak için kullanılabilecek ikinci seçenek, var olan bir API Tanım Belgesinin içeri aktarılmasıdır. Bunun için API Tanım Belgesini İçe Aktar (Import API Spec) seçeneği seçilir.

İçe aktarılmak üzere iki standart desteklenmektedir. Bunlar OpenAPI 3.0.x ve OpenAPI 2.x (Swagger) standartlarıdır.

Seçilen standarda uygun dosyanın içeri aktarılabilmesi için URL Girme ve Dosya Yükleme (Upload File) seçenekleri bulunmaktadır.

Spec Authorization Kullan (Use Spec Authorization)

Bazı tanım dosyaları, içeriklerinin görüntülenebilmesi için istemcinin yetkilendirilmiş olduğunu kontrol eder. Bunun için HTTP isteği içerisinde kimlik doğrulama verilerinin gönderilmesi gerekir. Eğer erişilecek URL'deki tanım dosyası böyle bir dosya ise, bu kutu işaretlenerek kimlik bilgilerini girilir.

Spec Authorization Kullan seçeneği işaretlenirse isteğe bağlı Temel Kimlik Doğrulama alanları ve Spec Authorization Listesi tablosu görünür; listede Key Name, Value ve Type sütunlarıyla yetkilendirme anahtarları eklenir.

URL Girme

Var olan API Tanım Dosyasına erişilebilecek adres URL alanına girilerek Ayrıştır (Parse) tuşuna tıklanır.

Dosya Yükleme

Yükleme tuşuna tıklanıp var olan API Tanım Dosyası seçilerek Ayrıştır (Parse) tuşuna tıklanır.

Her iki yöntemde de ayrıştırma işleminin sonucunda Başlık (Title), Açıklama ve Sunucular (Servers) alanları gelir. Boş API oluşturmadan farklı olarak bu alanların değerleri içe aktarılan API Tanım Dosyası içinden alınır. Bu aşamadan sonra sağ üstteki Oluştur (Create) tuşu tıklanabilir hale gelir ve bu tuşa basılarak tanım dosyası kaydedilebilir.

API Tanım Belgesi Güncelleme

API Tanım Belgesi listesinde bir kaydın Başlık kolonundaki değere tıklandığında ya da o kaydın en sağdaki kolonunda bulunan menü tuşuna tıklanıp Güncelle (Edit) seçeneği seçildiğinde, API Tanım Dosyası güncelleme arayüzü açılır.

API Tanım Belgesi ayarları aşağıdaki görselde gösterilmektedir:

Genel Bakış (API Overview)

Güncelleme arayüzü ilk açıldığında Genel Bakış (API Overview) açılır. Genel Bakış bağlantısı arayüzün sol tarafındadır.

Adresler (Paths)

Genel Bakış bağlantısının hemen altında Adresler (Paths) bölümü vardır.

Adres (Path), bir API'nin istek gönderilebilecek adreslerinden her birine verilen isimdir.

Adres Ekleme

API'nin adreslerine bir yenisini eklemek için, Adresler bölümünün başlığının altındaki + Yeni tuşuna tıklanır.

Açılan pencerede eklenmek istenen adres girilerek Kaydet tuşuna tıklanır.

Adres Silme

Listedeki adreslerden herhangi birine tıklandığında o adres seçilmiş olur ve sağ tarafta o adrese ilişkin detayların yönetilebileceği bir bölüm görüntülenir. Bu bölümün sağ üst kısmındaki Sil (Delete) tuşuna tıklanarak adres silinebilir.

Adres Güncelleme

Listedeki adreslerden herhangi birine tıklandığında o adres seçilmiş olur ve sağ tarafta o adrese ilişkin detayların yönetilebileceği bir bölüm görüntülenir.

Adresi Değiştirme

Sağ tarafta en üstte adres bir bağlantı olarak görüntülenir. Bu bağlantının yanındaki Düzenle (Edit) butonuna tıklandığında, açılan pencereden adres güncellenebilir.

Adres düzenleme ayarları aşağıdaki görselde gösterilmektedir:

İşlemler (Operations)

Bir Adres seçildiği zaman arayüzün sağ tarafında o adrese tanımlanmış olan İşlemler (Operations)'in yönetilebileceği bir bölüm gelir.

İşlem (Operation): Bir API'nin, tanımlı adresleri üzerinden istek kabul ettiği her bir geçerli HTTP Metodu ile bu metoda ilişkin kimlik ve tanımlayıcı bilgiler, parametreler, istek ve yanıt içeriklerinden oluşur.

Herhangi bir adres seçildiğinde, o adres için tanımlanmış olan İşlemlerden ilki seçili olarak görüntülenir.

uyarı

Seçilen işlem, HTTP Metot adını içeren kutucuğun alt kısmındaki ince mavi çizgi ile gösterilir.

Yukarıdaki görselde /pet/findByStatus adresinin kullanıcı tarafından seçilmiş olduğu, bu adreste tanımlanmış olan Get işleminin de otomatik olarak seçilerek detayının görüntülenmiş olduğu görülmektedir.

Kimlik ve Tanımlama Alanları

Kimlik ve Tanımlama Alanları için kullanılan alanlar aşağıdaki tabloda görülmektedir.

Alan	Açıklama
Özet (Summary)	İşlemin ne yaptığına ilişkin kısa bilgidir. Girilmesi isteğe bağlıdır.
İşlem ID (Operation ID)	İşlemin biricik anahtarıdır. • API'nin tüm işlemleri arasında benzersiz olmalıdır. • Büyük/küçük harfe duyarlıdır. • Araçlar ve kitaplıklar bir işlemi benzersiz şekilde tanımlamak için bu değeri kullanabileceğinden, yaygın programlama adlandırma kurallarına uyulması ÖNERİLİR.
Açıklama	İşlem davranışının ayrıntılı bir açıklamasıdır. Girilmesi isteğe bağlıdır.
Etiketler (Tags)	Etiketler, işlemlerin kaynaklara veya diğer niteleyicilere göre mantıksal olarak gruplandırılması için kullanılabilir. Girilmesi isteğe bağlıdır. Birden çok eklenebilir.

Başlık Parametreleri (Header Parameters)

Bu, İşleme gönderilebilecek başlıkların yönetildiği bölümdür.

Sorgu Parametreleri (Query Parameters)

Bu, İşlemin alabileceği sorgu parametrelerinin yönetildiği bölümdür.

İstek Gövdesi (Request Body)

Bu, İşlem için örnek istek gövdelerinin yönetilebileceği bölümdür. Bir ya da daha fazla Medya Tipi (Media Type) için örnek istek gövdesi tanımlanabilir.

Yanıtlar (Responses)

Bu İşlem için döndürülebilecek Yanıt (Response)'ların yönetilebileceği bölümdür.

Her bir yanıt, bir HTTP Durum Kodu (HTTP Status Code), o durum kodunun açıklaması ile, bir ya da daha fazla Medya Tipi (Media Type) için oluşturulmuş Yanıt Gövdesi (Response Body)'den oluşur.

bilgi

Apinizer, bir Medya Tipi için birden çok muhtemel yanıt gövdesinin ve bunların hangi koşullarda döndürülebileceğinin tanımlanmasına olanak verir.

Aşağıdaki görselde şunlar görülmektedir:

• Bu İşlem için 200 ve 400 kodları döndürülebilir.
• 200 kodu için application/json ya da application/xml olmak üzere iki farklı Medya Tipinden yanıt dönebilir.
• application/json Medya Tipi için status parametresinin değeri "pending" ise birinci satırdakine, "sold" ise ikinci satırdakine benzer bir yanıt gövdesi dönecektir.

İşlem Ekleme

Bir Adres seçildiğinde, o Adres için tanımlanmış olan İşlemler, ilgili HTTP Metotları renklendirilerek gösterilir. Renklendirilmemiş HTTP Metotları için henüz bir İşlem tanımlanmamış demektir. Bunlardan herhangi birisi için İşlem tanımlanmak istenirse, istenen HTTP Metodu seçilir. Bu seçim ile birlikte, henüz bir İşlem tanımlanmadığı görülür. İşlem Yeni İşlem (Add Operation) tuşuna basılarak seçilmiş olan metot için İşlem eklenebilir.

İşlem Silme

Bir İşlem seçildiğinde, pencerenin sağ tarafında bir Sil (Delete) tuşu görünür. Bu tuşa tıklanarak seçilmiş olan İşlem silinebilir. Aşağıdaki görselde, Delete işleminin seçildiği ve bu işlemin silinebilmesi için kullanılacak Sil tuşu görülmektedir.

Veri Modelleri

Arayüzün sol tarafının alt kısmında bu API'nin kullandığı ve standart temel tiplerden (primitive types) olmayan veri tipleri görüntülenir.

Veri Modeli Ekleme

Yeni bir veri modeli eklemek için bölümün başlığının altındaki + Yeni tuşuna tıklanır.

Açılan pencerede veri modelinin adı ve açıklaması girilerek Kaydet tuşuna tıklanır.

Veri Modeli Import Etme

Spec içerisindeki Veri Modellerine, Ortak Sorgu Modeli sayfası üzerinden eklenmiş modeller aktarılabilir.

Veri Modeli Silme

Herhangi bir veri modelinin üzerine tıklandığında sağ tarafta o veri modelinin detayı görüntülenir. Açılan bu bölümün sağ üst kısmındaki Sil (Delete) tuşuna tıklanarak veri modeli silinebilir.

Veri Modeli Güncelleme

Herhangi bir veri modelinin üzerine tıklandığında sağ tarafta o veri modelinin detayı görüntülenir. Bu bölümde, veri modelinin adı, açıklaması ve özellikleri (properties) bulunur.

Veri Modelinin Adını Değiştirme

Veri modelinin adının yanındaki Düzenle (Edit) simgesine tıklandığında adın güncellenebileceği bir metin kutusu açılır. İstenen değişiklik bu alanda yapılır.

Özellikler (Properties)

Veri modelinin alt alanlarından her birine Özellik (Property) adı verilir. Bir veri modeli Nesneye Yönelik Programlamadaki bir Sınıf (Class), bir özellik ise bu sınıfın içindeki özellik (property) ya da nitelik (attribute) olarak görülebilir.

Özellik Ekleme

Özellikleri içeren tablonun kolon başlıkları satırının en sağında bulunan + tuşuna tıklandığında yeni bir özellik girilebilecek bir pencere açılır.

Açılan penceredeki veri alanları doldurularak Kaydet tuşuna tıklanır.

Özellik eklemek için kullanılan alanlar aşağıdaki tabloda görülmektedir.

Alan	Açıklama
Ad	Özelliğin adıdır. Zorunludur ve Veri Modelinin bütün Özellikleri içinde biricik (unique) olmalıdır.
Açıklama	Özelliğin ne olduğuna, nasıl kullanılacağına ilişkin açıklamadır. Doldurulması isteğe bağlı alandır.
Zorunlu (Required)	Bu özelliğin değerinin olmasının zorunlu olup olmadığını belirtir.
Tip	Özelliğin tipidir. Temel türler ya da API içinde tanımlanmış olan tipler kullanılabilir. Zorunlu alandır.

Özellik Silme

Özellikler tablosundaki her özelliğin satırının sonundaki menüden o özelliği silmek için kullanılabilecek **Kaldır ** tuşu bulunur.

Özellik Güncelleme

Özelliklerden herhangi birinin Ad kolonundaki değerine tıklanırsa, o özelliğin güncellenebileceği pencere açılır. Güncellemeler yapıldıktan sonra Kaydet tuşuna basılarak güncelleme işlemi tamamlanır.

API Tanım Belgesi Silme

API Tanım Belgesi listesinde silinmek istenen kaydın en sağdaki kolonunda bulunan menü tuşuna tıklanıp **Kaldır ** seçilerek kayıt silinebilir.

API Proxy Oluşturma

API Tanım Belgesi'nin güncelleme arayüzünde API Proxy Oluştur (Create API Proxy) tuşuna tıklanarak bu API Spec kullanılarak bir API Proxy oluşturulabilir.

uyarı

API Tanım Dosyası kullanılarak API Proxy oluşturulurken, tanım dosyasında bulunan tanımlar API Proxy için şablon olarak kullanılır. API Proxy oluşturulduktan sonra Spec Tasarım Editörü üzerinden tanım dosyasında yapılan değişiklikler API Proxy'i, API Proxy'nin Tasarım sekmesinden yapılan değişiklikler ise API Tanım Dosyasını etkilemez.

uyarı

Bir API Tanım Dosyası kullanılarak birden çok API Proxy oluşturulabilir.

Spec Tasarım Editörü Kullanım Senaryoları

Spec first yaklaşımı ile API geliştirme senaryoları:

Spec First API Geliştirme

1. Boş API Spec oluşturma
2. Endpoint'leri ve işlemleri tanımlama
3. Veri modellerini oluşturma
4. Spesifikasyonu doğrulama
5. Spec'ten API Proxy oluşturma
6. Otomatik dokümantasyon oluşturma

Mevcut API Dokümantasyonu

1. Mevcut API Spec'i içe aktarma
2. Spesifikasyonu düzenleme ve güncelleme
3. Endpoint ve veri modellerini iyileştirme
4. Örnekler ve açıklamalar ekleme
5. Spec'ten API Proxy oluşturma

Spec Tasarım Editörü ve API Designer İlişkisi

Spec Tasarım Editörü, API Designer'ın spec first yaklaşımında merkezi rol oynar. İşleyiş akışı:

Spec Tasarım Editörü
   │
   │ OpenAPI/Swagger Spec
   │ (Spec First)
   │
   ▼
Ortak Veri Modelleri
   │
   │ Model İçe Aktarma
   │ $ref Referansları
   │
   ▼
API Spec
   │
   │ Spec'ten API Proxy Oluşturma
   │
   ▼
API Proxy
   │
   │ Konfigürasyon
   │
   ▼
API Gateway

1. Spec Oluşturma

Spec Tasarım Editörü'nde OpenAPI/Swagger spesifikasyonu oluşturulur

Boş API veya içe aktarma ile Spec oluşturma.

2. Endpoint ve İşlem Tanımlama

Path'ler ve operation'lar tanımlanır

HTTP metotları, parametreler ve yanıtlar yönetilir.

3. Veri Modeli Yönetimi

Veri modelleri oluşturulur veya içe aktarılır

Ortak veri modelleri kullanılabilir.

4. API Proxy Oluşturma

Spec'ten API Proxy oluşturulur

Otomatik olarak API Proxy oluşturma ve konfigürasyon.

bilgi

Spec Tasarım Editörü ve API Designer arasındaki bu entegrasyon, spec first yaklaşımı ile API tasarımından deployment'a kadar kesintisiz bir süreç sağlar. Spesifikasyon önce oluşturulur, sonra bu spesifikasyondan API Proxy ve dokümantasyon otomatik olarak üretilir.

Spec Tasarım Editörü Avantajları

Spec first yaklaşımının sağladığı avantajlar:

Spec First Yaklaşımı

• API tasarımı spesifikasyon ile başlar
• Standart OpenAPI/Swagger formatı
• Kod yazmadan API tasarımı

Form Tabanlı Düzenleme

• Formlar üzerinden kolay düzenleme
• Görsel arayüz ile yönetim
• Validation ve hata kontrolü

Otomatik Üretim

• Spesifikasyondan API Proxy oluşturma
• Otomatik dokümantasyon üretimi
• Tutarlı API yapısı

Standart Uyumluluk

• OpenAPI/Swagger standartlarına uyum
• OpenAPI 3.0.x ve Swagger 2.x desteği
• Interoperability ve tool desteği

Sonraki Adımlar

Ortak Veri Modeli

Ortak veri modelleri oluşturma

API Proxy Oluşturma

API Tanım Belgelerinden API Proxy oluşturma

Quick Start

Hızlı başlangıç kılavuzu

API Designer

API Designer bileşenini öğrenin