Ana içeriğe atla

​
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şturulurAPI tasarımı spesifikasyon ile başlar.

Form Tabanlı Düzenleme

Formlar üzerinden veri girişi yapılırKod yazmadan API Spec oluşturma ve düzenleme.

İçe Aktarma Desteği

Var olan API Spec’ler içe aktarılabilirOpenAPI 3.0.x ve Swagger 2.x desteği.

API Proxy Oluşturma

Spesifikasyondan API Proxy oluşturulurAPI Spec’ten otomatik API Proxy oluşturma.
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:
  • Boş API Spec oluşturma
  • Var olan Spec’i içe aktarma
  • URL veya dosya yükleme
  • Spec authorization desteği
  • Path (adres) tanımlama
  • HTTP method belirleme
  • Operation (işlem) yönetimi
  • Parametre tanımları
  • 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. API Tanım Belgesi Listesi 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şturma 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. Boş API Seçeneği Yeni API Tanım Belgesi arayüzü için kullanılan alanlar aşağıdaki tabloda görülmektedir.
AlanAçı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çıklamaAPI 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 - URLAPI’ye erişilebilecek adrestir. Zorunludur.
Sunucu - AçıklamaBu 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. API Tanım Belgesini İçe Aktar İç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 aşağıdaki tablo gelir ve yetkilendirme için gerekli olan anahtarlar eklenir. Spec Authorization

​
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 Güncelleme API Tanım Belgesi ayarları aşağıdaki görselde gösterilmektedir: API Tanım Belgesi Ayarları

​
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. Genel Bakış

​
Adresler (Paths)

Genel Bakış bağlantısının hemen altında Adresler (Paths) bölümü vardır. Adresler 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. Adres Ekleme Açılan pencerede eklenmek istenen adres girilerek Kaydet tuşuna tıklanır. Adres Ekleme Dialog

​
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 Silme

​
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. Adres Güncelleme
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 Adres düzenleme ayarları aşağıdaki görselde gösterilmektedir: Adres Düzenleme Dialog
İş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.
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.
AlanAçı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. Başlık Parametreleri
Sorgu Parametreleri (Query Parameters)
Bu, İşlemin alabileceği sorgu parametrelerinin yönetildiği bölümdür. Sorgu Parametreleri
İ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. İstek Gövdesi
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.
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.
Yanıtlar
İş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 Ekleme
İş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. İşlem Silme

​
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 Modelleri

​
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. Veri Modeli Ekleme 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 Import

​
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 Silme

​
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. Veri Modelinin Adını Değiştirme
Ö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. Özellikler
Ö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. Özellik Ekleme Dialog Açılan penceredeki veri alanları doldurularak Kaydet tuşuna tıklanır. Özellik Ekleme Dialog Detay Özellik eklemek için kullanılan alanlar aşağıdaki tabloda görülmektedir.
AlanAçı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 Silme
Ö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 Tanım Belgesi Silme

​
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. API Proxy Oluşturma
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.
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şturulurBoş API veya içe aktarma ile Spec oluşturma.

2. Endpoint ve İşlem Tanımlama

Path’ler ve operation’lar tanımlanırHTTP metotları, parametreler ve yanıtlar yönetilir.

3. Veri Modeli Yönetimi

Veri modelleri oluşturulur veya içe aktarılırOrtak veri modelleri kullanılabilir.

4. API Proxy Oluşturma

Spec’ten API Proxy oluşturulurOtomatik olarak API Proxy oluşturma ve konfigürasyon.
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