M

MLOG

Türkçe

OpenAPI Spesifikasyonunun (OAS) gücünü keşfedin. Bu rehber, temel kavramlar ve faydalardan pratik örneklere ve API öncelikli tasarımın geleceğine kadar her şeyi kapsar.

API Dokümantasyonunda Evrim: OpenAPI Spesifikasyonu İçin Kapsamlı Bir Rehber

Günümüzün hiper bağlantılı dijital dünyasında, Uygulama Programlama Arayüzleri (API'ler) yazılımlarımızı ve hizmetlerimizi birbirine bağlayan görünmez ipliklerdir. Mobil bankacılıktan sosyal medya akışlarına kadar her şeyi mümkün kılan modern dijital ekonominin motorudurlar. Ancak API'lerin sayısı katlanarak arttıkça, kritik bir zorluk ortaya çıkıyor: geliştiriciler, sistemler ve kuruluşlar nasıl etkili ve belirsizliğe yer bırakmadan iletişim kurabilir? Dünyanın bir ucunda oluşturulmuş bir API'nin, başka bir yerdeki bir hizmet tarafından sorunsuzca tüketilebildiğinden nasıl emin olabiliriz?

Cevap, hem insanların hem de makinelerin anlayabileceği bir şekilde bir API'nin yeteneklerini tanımlayan ortak bir dilde, evrensel bir sözleşmede yatmaktadır. İşte bu rolü OpenAPI Spesifikasyonu (OAS) üstlenir. OAS, sadece bir dokümantasyondan daha fazlası olup, RESTful API'leri tasarlamak, oluşturmak, belgelemek ve tüketmek için temel bir standarttır. Bu rehber, OpenAPI Spesifikasyonuna derinlemesine bir dalış yapmanızı sağlayacak; ne olduğunu, neden önemli olduğunu ve daha iyi, daha işbirlikçi dijital ürünler oluşturmak için onu nasıl kullanabileceğinizi keşfedeceksiniz.

OpenAPI Spesifikasyonu Nedir? API'ler İçin Evrensel Bir Dil

Özünde, OpenAPI Spesifikasyonu, RESTful API'ler için standart, dilden bağımsız bir arayüz tanımıdır. API'nizin tüm yapısını, genellikle YAML veya JSON formatında yazılmış tek bir dosyada tanımlamanıza olanak tanır. Bunu bir binanın detaylı planı olarak düşünün; herhangi bir inşaat başlamadan önce, plan her odayı, her kapıyı ve her elektrik prizini ana hatlarıyla belirtir. Benzer şekilde, bir OpenAPI belgesi şunları tanımlar:

Kısa Bir Tarihçe: Swagger'dan OpenAPI'ye

"Swagger" terimini OpenAPI ile birbirinin yerine kullanıldığını duymuş olabilirsiniz. İlişkilerini anlamak önemlidir. Spesifikasyon, 2010 yılında Reverb'de Tony Tam tarafından oluşturulan Swagger Spesifikasyonu olarak başladı. Büyük bir popülerlik kazandıkça, 2015 yılında Linux Vakfı'na bağışlandı ve Google, Microsoft ve IBM gibi endüstri liderlerinden oluşan bir konsorsiyum olan OpenAPI Initiative'in yönetimi altında gerçek bir açık standart olarak kurularak OpenAPI Spesifikasyonu olarak yeniden adlandırıldı.

Bugün, Swagger, OpenAPI Spesifikasyonu ile çalışan, etkileşimli dokümantasyon oluşturmak için Swagger UI ve spesifikasyonun kendisini yazmak için Swagger Editor gibi güçlü açık kaynaklı ve profesyonel araçlar setini ifade eder.

Bir OpenAPI Belgesinin Temel Bileşenleri

Bir OpenAPI belgesi, belirli alanlardan oluşan bir set ile yapılandırılmıştır. İlk bakışta göz korkutucu görünse de mantıksal olarak düzenlenmiştir. Bir OpenAPI 3.x belgesinin temel yapı taşlarını, daha iyi insan okunabilirliği için YAML kullanarak inceleyelim.

1. `openapi` ve `info` Nesneleri: Temel Bilgiler

Her OpenAPI belgesi bir sürüm ve temel üst verilerle başlar.

Örnek:


openapi: 3.0.3
info:
  title: Küresel Kitap Kataloğu API'si
  description: Dünya genelindeki kitapların bir kataloğuna erişim sağlayan bir API.
  version: 1.0.0
  contact:
    name: API Destek Ekibi
    url: http://www.example.com/support
    email: support@example.com
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html

2. `servers` Dizisi: API'nizi Nerede Bulabilirsiniz

servers dizisi, API'niz için temel URL'leri belirtir. Geliştirme, hazırlık (staging) ve üretim gibi farklı ortamlar için birden fazla sunucu tanımlayabilirsiniz. Bu, araçların ortamlar arasında kolayca geçiş yapmasını sağlar.

Örnek:


servers:
  - url: https://api.example.com/v1
    description: Üretim Sunucusu
  - url: https://staging-api.example.com/v1
    description: Staging Sunucusu

3. `paths` Nesnesi: API'nin Kalbi

Burası, API'nizin uç noktalarını tanımladığınız yerdir. paths nesnesi, tüm bireysel URL yollarını tutar. Her yol öğesi daha sonra o yolda gerçekleştirilebilecek HTTP operasyonlarını (get, post, put, delete, vb.) tanımlar.

Her operasyon içinde, aşağıdaki gibi detayları tanımlarsınız:

4. `components` Nesnesi: Yeniden Kullanılabilir Yapı Taşları

Kendinizi tekrar etmekten kaçınmak için (DRY ilkesini izleyerek), OpenAPI components nesnesini sağlar. Bu, yeniden kullanılabilir öğeleri tanımlayabileceğiniz ve $ref işaretçileri kullanarak spesifikasyonunuz boyunca bunlara başvurabileceğiniz güçlü bir özelliktir.

5. `security` Nesnesi: Kimlik Doğrulamayı Uygulama

Bileşenlerde securitySchemes'inizi tanımladıktan sonra, security nesnesi bunları uygulamak için kullanılır. Güvenliği tüm API'ye küresel olarak veya operasyon bazında uygulayabilir, böylece herkese açık ve korumalı uç noktaların bir karışımına izin verebilirsiniz.

Kuruluşunuz Neden OpenAPI'yi Benimsemeli: İş ve Teknik Faydalar

OpenAPI Spesifikasyonunu benimsemek sadece teknik bir seçim değil; tüm yazılım geliştirme yaşam döngüsü boyunca verimliliği, işbirliğini ve kaliteyi artıran stratejik bir karardır.

Geliştiriciler İçin: Tek Doğruluk Kaynağı

Ürün Yöneticileri ve Mimarlar İçin: Tasarım ve Yönetişim

Testçiler ve Kalite Güvence Ekipleri İçin: Kolaylaştırılmış Doğrulama

Son Kullanıcılar ve Ortaklar İçin: Üstün Bir Geliştirici Deneyimi (DX)

Pratik Rehber: İlk OpenAPI Belgenizi Oluşturma

Teoriyi pratiğe dökerek "Küresel Kitap Kataloğu API'miz" için temel bir OpenAPI 3.0 spesifikasyonu oluşturalım. Okunabilirliği için YAML kullanacağız.

Adım 1: Temel Bilgileri ve Sunucuları Tanımlayın

Üst veriler ve üretim sunucusu URL'si ile başlıyoruz.


openapi: 3.0.3
info:
  title: Küresel Kitap Kataloğu API'si
  description: Dünya genelindeki kitapların bir kataloğuna erişim sağlayan bir API.
  version: 1.0.0
servers:
  - url: https://api.globalbooks.com/v1

Adım 2: `components` İçinde Yeniden Kullanılabilir Bir Veri Modeli Tanımlayın

Uç noktalarımızı tanımlamadan önce, bir `Kitap` nesnesi için yeniden kullanılabilir bir şema oluşturalım. Bu, tasarımımızı temiz ve tutarlı tutar.


components:
  schemas:
    Book:
      type: object
      properties:
        isbn:
          type: string
          description: Uluslararası Standart Kitap Numarası.
          example: '978-0321765723'
        title:
          type: string
          description: Kitabın başlığı.
          example: 'The C++ Programming Language'
        author:
          type: string
          description: Kitabın yazarı.
          example: 'Bjarne Stroustrup'
        publicationYear:
          type: integer
          description: Kitabın yayınlandığı yıl.
          example: 2013
      required:
        - isbn
        - title
        - author

Adım 3: `paths` İçinde Uç Noktaları Tanımlayın

Şimdi iki uç nokta oluşturacağız: biri kitapların bir listesini almak için, diğeri ise ISBN'sine göre belirli bir kitabı almak için.

$ref: '#/components/schemas/Book' kullanımına dikkat edin. Yeniden kullanılabilir `Kitap` şemamıza bu şekilde referans veriyoruz.


paths:
  /books:
    get:
      summary: Mevcut tüm kitapları listele
      description: İsteğe bağlı olarak filtrelenmiş bir kitap listesi döndürür.
      operationId: listBooks
      responses:
        '200':
          description: Kitap dizisi içeren başarılı bir yanıt.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Book'

  /books/{isbn}:
    get:
      summary: ISBN'ye göre bir kitap al
      description: ISBN'si ile tanımlanan tek bir kitabı döndürür.
      operationId: getBookByIsbn
      parameters:
        - name: isbn
          in: path
          required: true
          description: Alınacak kitabın ISBN'si.
          schema:
            type: string
      responses:
        '200':
          description: İstenen kitap.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Book'
        '404':
          description: Belirtilen ISBN'ye sahip kitap bulunamadı.

Adım 4: Güvenlik Ekleme

API'mizi bir başlıkta gönderilmesi gereken basit bir API anahtarıyla koruyalım. Önce şemayı `components` içinde tanımlıyor, sonra küresel olarak uyguluyoruz.


# Bunu 'components' bölümüne ekleyin
components:
  # ... önceki şemalar
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-KEY

# Bunu belgenin kök düzeyine ekleyin
security:
  - ApiKeyAuth: []

Adım 5: Doğrulama ve Görselleştirme

Tamamlanmış YAML dosyanızla artık çeşitli araçları kullanabilirsiniz:

OpenAPI Ekosistemi: Araçlar ve Teknolojiler

OAS'nin gücü, geniş ve olgun araç ekosistemi tarafından artırılır. İhtiyacınız ne olursa olsun, muhtemelen bunun için bir araç vardır:

OpenAPI'nin Geleceği: OAS 3.1 ve Ötesi

OpenAPI Spesifikasyonu sürekli olarak gelişmektedir. En son ana sürüm olan OAS 3.1, birkaç önemli iyileştirme getirdi:

Bu ilerlemeler, OpenAPI'nin modern, API öncelikli ve olay güdümlü bir mimaride merkezi bir eser olarak konumunu sağlamlaştırmaktadır.

Sonuç: Modern Geliştirmenin Temel Taşı

OpenAPI Spesifikasyonu, API'ler hakkında düşünme şeklimizi dönüştürdü. API dokümantasyonunu korkulan, genellikle ihmal edilen bir sonradan düşünceden, tüm geliştirme yaşam döngüsünü yönlendiren stratejik, yaşayan bir belgeye yükseltti. Makine tarafından okunabilir bir sözleşme olarak hizmet ederek OAS, işbirliğini teşvik eder, güçlü otomasyonu mümkün kılar, tutarlılığı zorunlu kılar ve nihayetinde daha iyi, daha güvenilir ve daha kolay tüketilebilir API'lerin oluşturulmasına yol açar.

İster bir geliştirici, mimar, ürün yöneticisi veya testçi olun, OpenAPI Spesifikasyonunu benimsemek, modern yazılım geliştirmede ustalaşmaya yönelik kritik bir adımdır. Henüz kullanmıyorsanız, bir sonraki projenizle başlamayı düşünün. Önce sözleşmeyi tanımlayın, ekibinizle paylaşın ve dijital işbirliklerinizde yeni bir verimlilik ve netlik seviyesinin kilidini açın.