Büyük veya karmaşık projeler için API'ler geliştirme ve belgeleme konusunda yardıma mı ihtiyacınız var? Korkmayın! Sizin için tam da çözüme sahibiz - OpenAPI Şartnamesi (eski adıyla Swagger Şartnamesi). Bu ücretsiz ve açık kaynaklı standart, API geliştirme ve dokümantasyonu çocuk oyuncağı haline getiriyor! OpenAPI ile, anlaşılması kolay, standart bir format kullanarak kolayca API'ler oluşturabilir ve belgeleyebilirsiniz.
Karmaşık API geliştirme ve dokümantasyonunu anlamaya çalışarak zaman kazanın. OpenAPI ile süreci basitleştirmenize yardımcı olalım!
OpenAPI Şartnamesi (OAS) Nedir?
OpenAPI, bir RESTful API'nin yapısını tanımlayan ve yeteneklerini açıklayan bir spesifikasyondur. OpenAPI Şartnamesi, geliştiricilerin API'leri verimli bir şekilde keşfetmelerini ve nasıl çalıştıklarını anlamalarını sağlayan, API'leri belgelemek ve onlarla etkileşim kurmak için standart bir yol sağlar. RESTful API'ler, veri iletimi için HTTP protokolünü kullanır ve bu da farklı programlama dillerinde yazılmış platformların ve sistemlerin iletişim kurmasını kolaylaştırır.
OpenAPI ile, bir API'nin nasıl çalıştığını anlamak için kaynak koduna veya ağ trafiği incelemesine erişmenize gerek yoktur. API tanımının kendisi ihtiyacınız olan tüm bilgileri sağlar.
OpenAPI Formatı
OpenAPI'nin en son sürümü 3.0'dır. OpenAPI tanımları JSON veya YAML ile yazılabilir. JSON, uzun uzadıya bir API açıklaması yazmak ve OpenAPI yapısını takip etmek yerine, verileri anahtar-değer çiftleri kullanarak temsil eder. Bir API'nin yeteneklerini, kaynak koduna veya dokümantasyonuna erişiminiz olmasa bile anlamayı kolaylaştırır.
JSON Formatında OpenAPI 3.0 spesifikasyon örneği:
{
"openapi": "3.0.0",
"info": {
"title": "API Title",
"description": "API Description",
"version": "1.0.0"
}
}
}
Örneğin, Geleneksel dokümantasyonda, her API metodu için ayrı bir bölüm yazarak ne yaptığını ve nasıl kullanılacağını açıklarsınız. OpenAPI, bu bilgileri bir dizi anahtar-değer çifti halinde düzenleyerek farklı bir yaklaşım benimser. Her metodun, istek parametreleri ve yanıt kodları dahil olmak üzere, onu tanımlayan bir dizi özelliği vardır.
JSON, OpenAPI için standart format olsa da, daha basit bir işaretleme dili olan YAML'i de kullanabilirsiniz. OpenAPI belgeleri oluşturmayı ve düzenlemeyi daha da kolaylaştırır.
openapi: 3.0.0
info:
title: API Title
description: API Description
version: 1.0.0
İşte size - OpenAPI'nin temelleri. Başlangıçta biraz teknik görünebilir, ancak bir kez alıştıktan sonra, onsuz nasıl yaşadığınızı merak edeceksiniz.
OpenAPI şartnamesi, JSON Schema Specification'da tanımlanan JSON veri türlerini kullanır. Bu veri türleri arasında tamsayılar, sayılar, boole değerleri ve dizeler bulunur. Ayrıca, bu veri türlerinin formatını 'format' özelliği (örneğin int32, int64, float, double, binary, data, date-time ve password formatı) kullanarak değiştirebilirsiniz. OpenAPI ayrıca, JSON spesifikasyonu altında tanımlanan modellerin (nesnelerin) şema nesneleri olarak kullanılmasına da izin verir.
OpenAPI Yapısı
OpenAPI şartnamesi, REST API'lerin yapısını ve davranışını açıklayan bir belgedir. OpenAPI belgesini daha derinlemesine inceleyelim.
Bir OpenAPI belgesi, ilgili anahtar-değer çiftlerini gruplandıran nesnelerden veya nesne dizilerinden oluşan yapılandırılmış bir formata sahiptir. Bir OpenAPI belgesindeki ilk köşeli parantez kümesi {} tüm özellikleri içerir ve "belge nesnesi" olarak adlandırılır. Bazı esneklikler olsa da, OpenAPI belgeleri temel bir yapıya uymalıdır. Bazı üst düzey bölümler zorunluyken, diğerleri isteğe bağlıdır ve farklı API'lerde OpenAPI spesifikasyonlarında değişikliklere izin verir.
Bir OpenAPI belgesi aşağıdaki bölümleri içerebilir:
- OpenAPI: API, araçların OpenAPI spesifikasyonunu ayrıştırmasını ve dokümantasyon oluşturmasını sağlamak için OpenAPI sürümünün belirtilmesini gerektirir.
- Info: Bu alan, API'nin başlığı, açıklaması ve sürümü gibi API hakkında meta veriler içerir. Çeşitli araçlar bu bilgiden yararlanabilir.
- Servers: OpenAPI Şartnamesindeki bu alan, her biri sunucu ana bilgisayarı için bir URL ve sunucu hakkında kısa bir açıklama içeren bir dizi sunucu nesnesinden oluşur. Bu bilgiler, sunucuyla etkileşim kurmak için kullanabileceğiniz bağlantı ayrıntılarını sağlar.
- Paths: Bu nesne, API'nin ayrı uç noktalarına giden göreli yolları içerir. Her yol, POST, GET, PUT veya DELETE gibi API ile etkileşim kurmak için kullanılabilen işlemleri içerir.
- Components: OpenAPI Şartnamesindeki bu alan, istek gövdeleri, yanıt şemaları ve güvenlik şemaları için yeniden kullanılabilir şemalar içeren bir nesnedir. Bu şemalar, özellikle yol nesnesinde olmak üzere, $ref etiketi kullanılarak spesifikasyon boyunca referans verilebilir.
- Security: İstekleri yetkilendiren güvenlik şemasının türünü bildiren bir nesne. Bir güvenlik nesnesi genel olarak tanımlanır veya ayrı işlemler tarafından geçersiz kılınır.
- Tags: Dokümantasyonda API kaynaklarını hangi sırada görüntülemeniz gerektiğini belirten meta veriler içeren bir nesne.
- ExternalDocs: Kullanıcı kılavuzları gibi ek dokümantasyona bağlanan bir nesne.
İşte YAMLJSON formatında gerekli alanlara sahip bir OpenAPI belgesinin temel şablonu.
POST İsteği
Aşağıdaki örnek, bir evcil hayvanın resmini yüklemek için bir POST isteği için bir uç nokta tanımlar.
openapi: 3.0.3
info:
title: Swagger Petstore - OpenAPI 3.0
version: 1.0.11
servers:
- url: https://petstore3.swagger.io/api/v3
tags:
- name: pet
description: Everything about your Pets
paths:
/pet/{petId}/uploadImage:
post:
tags:
- pet
summary: uploads an image
description: ''
operationId: uploadFile
parameters:
- name: petId
in: path
description: ID of pet to update
required: true
schema:
type: integer
format: int64
- name: additionalMetadata
in: query
description: Additional Metadata
required: false
schema:
type: string
requestBody:
content:
application/octet-stream:
schema:
type: string
format: binary
responses:
'200':
description: successful operation
Yukarıdaki kod parçasını https://editor.swagger.io/ adresinde çalıştırabilirsiniz. Çıktı aşağıdaki gibi olacaktır.
Kod parçacığı, API'nin başlığı ve sürümü gibi temel bilgiler sağlayarak başlar. Ayrıca, API sunucusu için temel URL'yi belirtir.
tags bölümü, evcil hayvanlarla ilgili tüm uç noktaları gruplandıran "pet" adlı bir etiket tanımlar. paths bölümü, /pet/{petId}/uploadImage uç noktası için tanımı içerir.
/pet/{petId}/uploadImage uç noktası, bir evcil hayvan için bir resim yüklemek için bir POST metodunu destekler. parameters bölümü, güncellenecek evcil hayvan kimliğini ve yüklenen resim için ek meta verileri belirten "petId" ve "additionalMetadata" olmak üzere iki parametre tanımlar.
request body bölümü, ikili formatta olması beklenen istek gövdesinin yapısını belirtir. responses bölümü, başarılı işlemi gösteren tek bir yanıt kodu olan 200'ü tanımlar.
OpenAPI'nin Faydaları Nelerdir?
OpenAPI Şartnamesi, API'ler oluşturan ve belgeleyen geliştiriciler için çeşitli avantajlar sunar.
OpenAPI Şartnamesi, daha iyi işbirliği, tutarlılık, kod oluşturma, doğrulama ve araçlar aracılığıyla API geliştirmeyi kolaylaştırır. API'leri tanımlamanın standartlaştırılmış ve şeffaf bir yolu, ekiplerin etkili bir şekilde birlikte çalışmasını basitleştirirken, API dokümantasyonunda tutarlılık sağlar.
Geliştiriciler, birden fazla programlama dilinde API'ler için kod oluşturabilir ve diller arasında tutarlılığı koruyabilir. Oluşturulan dokümantasyon dosyaları güvenilir ve tutarlıdır ve aynı zamanda geliştiriciler için zaman kazandırır.
Doğrulama araçları uyumluluğu garanti etmeye ve hataları önlemeye yardımcı olurken, zengin bir araç ekosistemi tüm API geliştirme sürecini kolaylaştırır. OpenAPI Şartnamesi, hataları azaltır ve sonuçta ortaya çıkan yazılım projelerinin kalitesini artırır.
OpenAPI Şartnamesi Nasıl Oluşturulur?
Peki ya kodu manuel olarak yazmaktan kaçınmayı tercih ederseniz? Endişelenmeyin, yardım etmek için buradayız! Apidog , OpenAPI Şartnamesi ile çalışmayı kolaylaştıran bir araçtır. API'leri tasarlamayı, test etmeyi ve yayınlamayı basitleştiren bulut tabanlı bir platformdur. Bununla, geliştiriciler sezgisel bir görsel düzenleyici kullanarak OpenAPI spesifikasyonları oluşturabilir ve düzenleyebilir.
Apidog ayrıca, geliştiricilerin API'lerini doğrudan platformdan test etmelerini sağlayan yerleşik testler içerir. Geliştiricilerin diğer geliştiricilerden önceden oluşturulmuş API'leri keşfedebilecekleri ve kullanabilecekleri bir API pazarı sağlar. Bununla, sezgisel bir arayüz kullanarak API'lerinize hızlı bir şekilde yollar, parametreler ve yanıtlar ekleyebilirsiniz.
En iyi kısım? Apidog, dokümantasyonu otomatik olarak oluşturur. Sadece birkaç tıklamayla, OpenAPI spesifikasyonuna göre API'niz için güzel dokümantasyon oluşturabilirsiniz. Dokümantasyon, parametreleri, yanıtları ve örnekleri dahil olmak üzere her uç nokta hakkında bilgi içerir.
Bunu nasıl yapabileceğimize dair adım adım bir kılavuza bakalım. İşte bir OpenAPI spesifikasyon dosyasını Apidog'a içe aktarmak için adım adım bir süreç:
Adım 1. Apidog web sitesini açın
İlk olarak, web tarayıcınızda Apidog web sitesini açın. Web sitelerini ziyaret ederek erişebilirsiniz.
Adım 2. Hesabınıza Giriş Yapın
Mevcut bir API Dog hesabınız varsa, sayfanın sağ üst köşesindeki "Sign In" (Giriş Yap) düğmesini tıklayarak oturum açın. Bir hesabınız yoksa, "Sign Up" (Kaydol) düğmesini tıklayarak ve talimatları izleyerek bir tane oluşturabilirsiniz.
Adım 3. Yeni Bir Proje Oluşturun
Oturum açtıktan sonra, yeni bir proje oluşturmak için "Create Project" (Proje Oluştur) düğmesini tıklayın.
Adım 4. OpenAPI Dosyasını İçe Aktar
Proje oluşturma sayfasında bir OpenAPI spesifikasyon dosyası içe aktarın. Devam etmek için "Import" (İçe Aktar) düğmesini tıklayın.
Adım 5. OpenAPI Dosyanızı Yükleyin:
İçe aktarma sayfasında, OpenAPI dosyanızın URL'sini g irebileceğiniz bir alan göreceksiniz. Bir URL'niz yoksa, "or upload a file" (veya bir dosya yükle) seçeneğini tıklayarak ve dosyayı seçerek dosyayı yerel makinenizden yükleyebilirsiniz.
JSON Dosyamın URL'sini giriyorum.
Adım 6. İçe Aktarmanın Tamamlanmasını Bekleyin
OpenAPI dosyanızın boyutuna ve karmaşıklığına bağlı olarak, içe aktarma işlemi birkaç dakika sürebilir.
Apidog, dosyayı otomatik olarak ayrıştıracak ve hesabınızda yeni bir API oluşturacaktır.
Adım 7. API Ayarlarınızı Yapılandırın
OpenAPI dosyasını içe aktardıktan sonra, yeni API'niz için ayarlar sayfasına yönlendirileceksiniz. Bu sayfada, API'nizin adı, açıklaması ve kimlik doğrulama gereksinimleri gibi farklı ayarları yapılandırabilirsiniz.
Adım 8. API'nizi Oluşturmaya Başlayın
API ayarlarınızı yapılandırdıktan sonra, 'nin sezgisel arayüzünü kullanarak API'nize uç noktalar ve dokümantasyon ekleyebilirsiniz.
Bir OpenAPI spesifikasyon dosyasını Apidog'a içe aktarmanın basit adımlarını izleyerek, API projelerinizi daha verimli bir şekilde yönetebilir ve belgeleyebilirsiniz. Spesifikasyon dosyası tipik olarak POST uç noktası, yol, parametreler ve yanıt kodları gibi temel ayrıntıları içerir.
Şartname dosyanızı Apidog'a ekledikten sonra, API geliştirme sürecinizde tutarlılık ve güvenilirliği sağlamak için kullanıcı dostu API'sinden ve güçlü araçlarından yararlanabilirsiniz. Bu nedenle, zaman kazanmak ve API geliştirme sürecinizi kolaylaştırmak istiyorsanız, OpenAPI Şartnamesini Apidog ile kullanmayı düşünün.
