Kitap 03 · Backend ve API'lerSayfa 32 / 48

OpenAPI

Okunuşu: opın ey-pi-ay

Güncellendi 30 Eylül 20262 dk okuma

Kısaca

OpenAPI, HTTP API'lerini bir YAML veya JSON dosyasında tanımlayan açık bir standarttır; insanlar ve araçlar her endpoint'i, parametreyi ve yanıtı anlayabilir.

OpenAPI nedir?

OpenAPI, resmi adıyla OpenAPI Specification (OAS), çoğunlukla REST tarzı olan HTTP API'lerini YAML veya JSON ile yazılmış, makine tarafından okunabilir bir dosyada tanımlamak için kullanılan standart bir biçimdir. Dosya her endpoint'i, desteklediği HTTP metotlarını, parametrelerini, istek gövdelerini, olası yanıtlarını, veri şemalarını ve kimlik doğrulama yöntemlerini listeler. Swagger Specification'dan doğmuştur; bu spesifikasyon 2015'te bir Linux Foundation projesi olan OpenAPI Initiative'e bağışlanmış ve yeniden adlandırılmıştır. Güncel ana sürüm 3'tür.

Tanım yapılandırılmış veri olduğu için araçlar onunla çok şey yapabilir: geliştiricilerin istekleri tarayıcıda deneyebildiği etkileşimli dokümantasyon üretmek, birçok dilde istemci kütüphaneleri ve sunucu kodu üretmek, istekleri ve yanıtları doğrulamak, mock sunucular oluşturmak ve sözleşme testleri (contract tests) çalıştırmak. Ekipler ya önce OpenAPI dosyasını yazıp API'yi ona uygun kurar (design-first), ya da dosyayı koddaki açıklamalardan üretir (code-first).

OpenAPI belgesi bir binanın planı gibidir: inşaatçılar, denetçiler ve elektrikçiler binanın içinde dolaşmadan hepsi aynı çizimden çalışabilir. Herkese açık API'lerde ve dahili mikroservislerde yaygın olarak kullanılır; birçok API gateway da rotaları ve istek doğrulamasını yapılandırmak için OpenAPI dosyalarını içe aktarabilir.

OpenAPI ve Swagger sıklıkla eş anlamlı kullanılır, ancak bugün OpenAPI spesifikasyonun adıdır; Swagger ise onunla çalışan Swagger UI ve Swagger Editor gibi araçlar kümesini ifade eder. OpenAPI ayrıca farklı API stillerini tanımlayan GraphQL şemalarından ve gRPC .proto dosyalarından da farklıdır; AsyncAPI adlı ilgili bir standart ise olay güdümlü, mesaj tabanlı API'leri tanımlar.

Önemli noktalar

OpenAPI, HTTP API'lerini standart bir YAML veya JSON belgesinde tanımlar.
Endpoint'leri, parametreleri, istek ve yanıt şemalarını ve kimlik doğrulamayı kapsar.
Araçlar onu dokümantasyon, istemci SDK'ları, sunucu iskeletleri, mock sunucular ve testler üretmek için kullanır.
OpenAPI spesifikasyondur; Swagger ise onunla çalışan bir araçlar kümesinin adıdır.
Design-first ekipler spesifikasyonu koddan önce yazar; code-first ekipler onu koddan üretir.

Örnek

Minimal bir OpenAPI 3.1 belgesiyaml

openapi: 3.1.0
info: { title: Users API, version: 1.0.0 }
paths:
  /users/{id}:
    get:
      summary: Get a user by ID
      parameters:
        - { name: id, in: path, required: true, schema: { type: integer } }
      responses:
        "200":
          description: The user
          content:
            application/json:
              schema: { type: object, properties: { name: { type: string } } }
        "404": { description: No user with that ID }

Sık sorulan sorular

OpenAPI ile Swagger arasındaki fark nedir?

OpenAPI, HTTP API'lerini tanımlamaya yönelik spesifikasyonun adıdır. Swagger ise spesifikasyonun özgün adıydı ve şimdi OpenAPI dosyalarını okuyan ve düzenleyen Swagger UI ile Swagger Editor gibi araçlar kümesinin adıdır.

OpenAPI yalnızca REST API'leri için midir?

HTTP API'leri için tasarlanmıştır; pratikte bunlar çoğunlukla REST tarzı API'lerdir. GraphQL, gRPC ve mesaj tabanlı API'ler; GraphQL şemaları, Protocol Buffers ve AsyncAPI gibi başka biçimler kullanır.

OpenAPI dosyasını elle mi yazmalıyım, yoksa üretmeli miyim?

İki yaklaşım da yaygındır. Önce yazmak (design-first) ekiplerin kodlamadan önce API üzerinde anlaşmasına yardımcı olur; koddaki açıklamalardan üretmek (code-first) ise dosyayı uygulamayla otomatik olarak senkron tutar.

İlgili sayfalar

Bu sayfada bir hata ya da eksik mi gördünüz?Düzeltme önerin