OpenAPI dokumantasyonu

OpenAPI Specification (OAS), REST API'lerin makine tarafindan okunabilir sozlesmesini tanimlayan açık bir standarttir. YAML veya JSON formatinda yazilan bu spesifikasyon; endpoint listesi, parametreler, istek ve yanıt semalari, kimlik dogrulama gereksinimleri ve hata modellerini tek bir kaynakta toplar. Iyi bir OpenAPI dokumantasyonu sadece insan okuyucu icin degil, istemci SDK uretimi, mock sunucu, contract test ve API gateway konfigurasyonu icin de temel girdi olur.

OpenAPI vs Swagger

Swagger, OpenAPI spesifikasyonu etrafinda gelisen arac ekosisteminin tarihsel adidir. OpenAPI 3.x güncel standart surumudur. Swagger UI interaktif dokumantasyon arayuzunu, Swagger Editor düzenleme ortamini sağlar. Spesifikasyon ile araclari ayirt etmek ekip iletisimi acisindan önemlidir.

Temel dosya yapisi

openapi: 3.1.0
info:
  title: Siparis API
  version: 2.1.0
  description: Siparis yonetim servisi
servers:
  - url: https://api.example.com/v2
paths:
  /orders:
    get:
      operationId: listOrders
      parameters:
        - name: status
          in: query
          schema:
            type: string
            enum: [pending, shipped]
      responses:
        '200':
          description: Basarili
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderList'

Design-first vs code-first

Design-first yaklasimda once OpenAPI spesifikasyonu yazilir, ekip review eder, ardindan implementasyon yapilir. API sozlesmesi onceliklidir; breaking change erken yakalanir. Code-first yaklasimda controller ve DTO'lardan spesifikasyon uretilir; hiz kazanilir ancak dokumantasyon implementasyon detaylarina fazla bağımlı kalabilir.

• Design-first: Büyük ekipler, dis tuketiciler, uzun omurlu API'ler.
• Code-first: Hızlı prototip, ic API'ler, küçük ekipler.
• Hybrid: Taslak spec + codegen + annotation ile senkronizasyon.

components ve yeniden kullanım

components/schemas, components/responses, components/parameters ve components/securitySchemes bloklari tekrar eden tanimlari merkezilestirir. $ref ile referans vermek tutarlılığı artirir ve spec dosyasinin boyutunu yönetilebilir tutar.

components:
  schemas:
    ProblemDetails:
      type: object
      required: [type, title, status]
      properties:
        type: { type: string, format: uri }
        title: { type: string }
        status: { type: integer }
        detail: { type: string }
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

Semalar ve dogrulama

JSON Schema OpenAPI 3.x icinde şema tanımlamak icin kullanılır. required, enum, pattern, minimum, maximum ve format alanlari istemci ve sunucu tarafinda dogrulama sağlar. Nullable alanlar OpenAPI 3.0'da nullable: true, 3.1'de JSON Schema uyumlu type: ['string', 'null'] ile ifade edilir.

Örnek ve varsayilan degerler

example ve examples alanlari Swagger UI'da anlamli örnek yanitlar gösterir. default query parametreleri icin varsayilan degeri belirtir. Gercekci örnekler entegrasyon hatalarini azaltir.

Güvenlik tanimlari

OpenAPI güvenlik semalarini standart formatta tanimlar: API key, OAuth2, OpenID Connect, mutual TLS. Global security blogu ve endpoint bazli override ile hangi operasyonun hangi yetkiyi gerektirdigi açıktır.

1. securitySchemes tanımla.
2. Global veya path bazli security uygula.
3. Scope listesini OAuth2 flow icinde dokumante et.
4. Public endpoint'lerde bos security array kullan.

Swagger UI ve Redoc

Swagger UI interaktif deneme imkani sunar; geliştirme ortaminda hızlı test icin idealdir. Redoc okunabilir statik dokumantasyon üretir; dis geliştirici portali icin uygundur. Stoplight Elements ve Scalar gibi alternatifler modern UX ve tema destegi sağlar.

Üretim ortaminda dokumantasyonun hangi surumlerin açık olduğu kontrol edilmelidir. Internal API icin VPN veya SSO arkasinda sunmak yaygın bir pratiktir.

Kod uretimi

OpenAPI Generator, Kiota, NSwag ve benzeri araclar spec'ten istemci SDK, sunucu stub ve model siniflari üretir. Ayni spec'ten TypeScript, C#, Python ve Java istemcileri tutarlı tip tanimlariyla oluşturulabilir.

openapi-generator-cli generate \
  -i openapi.yaml \
  -g csharp \
  -o ./generated/client \
  --additional-properties=targetFramework=net8.0

Codegen ciktisi elle duzenlenmemeli; spec guncellenince yeniden uretilmelidir. CI pipeline'ina codegen adimi eklemek drift'i onler.

Contract testing

Pact, Dredd ve Schemathesis gibi araclar OpenAPI spec'i ile gerçek implementasyonu karsilastirir. Consumer-driven contract testlerinde istemci beklentileri spec'e yansir; provider bu spec'e uygunlugu dogrular.

CI entegrasyonu

• Spec degisikligi PR'da lint ve breaking change analizi.
• Implementasyon testleri spec'e karşı calistirilir.
• Spec ve kod ayni repoda veya spec repo'su versiyonlanir.

Surumleme ve OpenAPI

API versiyonu info.version, servers URL'si veya path prefix ile ifade edilir. Breaking change spec'te major versiyon artisi ile isaretlenmelidir. Spectral ve openapi-diff araclari geriye uyumsuz degisiklikleri otomatik tespit eder.

AsyncAPI ve olay tabanli API'ler

REST dışında mesaj ve olay tabanli API'ler icin AsyncAPI paralel bir spesifikasyon standardidir. Hibrit sistemlerde OpenAPI HTTP yuzeyini, AsyncAPI Kafka veya RabbitMQ kanallarini dokumante eder.

En iyi uygulama kontrol listesi

Her operasyon icin benzersiz operationId tanimlayin; codegen ve loglama icin kritiktir. Tüm hata yanitlarini ProblemDetails semasi ile modellleyin. Pagination parametrelerini ve link header semalarini dokumante edin. Deprecation icin deprecated: true ve açıklama ekleyin.

ASP.NET Core entegrasyonu

Swashbuckle ve NSwag ASP.NET Core projelerinde OpenAPI üretir. XML yorumlari, attribute'lar ve filter'lar ile spec zenginlestirilir. Minimal API'de WithOpenApi() ve endpoint metadata ile şema baglantisi kurulur.

builder.Services.AddSwaggerGen(options => {
  options.SwaggerDoc("v2", new OpenApiInfo { Title = "Siparis API", Version = "v2" });
  options.AddSecurityDefinition("Bearer", bearerScheme);
});

Mock sunucu ve geliştirme hizi

Prism, WireMock veya Stoplight Mock sunucu spec'ten mock yanıt üretir. Backend hazir olmadan frontend ve mobil ekipler entegrasyona baslayabilir. Örnek yanitlar spec'teki example alanlarindan turetilir.

Dokumantasyon kalitesi

Teknik dogruluk kadar okunabilirlik de önemlidir. Her endpoint icin is amaci aciklanmali, hata kodlari tablo halinde listelenmeli, rate limit ve auth gereksinimleri görünür olmalidir. Changelog spec veya ayri dosyada tutulabilir.

OpenAPI dokumantasyonu yasayan bir sozlesmedir. Implementasyon degistiginde spec güncellenmeli; spec degistiginde tuketiciler bilgilendirilmelidir. Tek kaynak prensibi, API ürün yonetiminin temelidir ve entegrasyon maliyetini uzun vadede dusurur.

Extensions ve vendor alanlari

x-* prefix ile özel alanlar eklenebilir: x-rate-limit, x-internal, x-codegen-hint. Bu alanlar standart disi bilgiyi tasir ancak arac destegi sinirli olabilir. Ekip icinde extension sozlugu dokumante edilmelidir.

Büyük spec yönetimi

Monolit spec dosyasi yuzlerce endpoint'te yonetilemez hale gelir. $ref ile moduler dosyalara bolme, domain bazli klasor yapisi ve bundling araci ile tek çıktı uretme yaygın cozumdur. Redocly CLI bundle ve lint islemlerini otomatiklestirir.

Erisilebilirlik ve çoklu dil

Dis geliştirici portali icin description alanlarinda Markdown destegi kullanılır. Türkçe ve Ingilizce description varyantlari description ve locale-specific extension ile sunulabilir. Örnek istek govdesi gerçek is senaryosunu yansitmali.

Performans ve spec boyutu

Asiri detayli spec Swagger UI yükleme suresini artirir. Lazy loading, tag bazli gruplama ve dis referans dosyalari performansi iyilestirir. Üretim portalinda yalnizca public operasyonlar gosterilebilir.

Breaking change yönetimi

openapi-diff ve Spectral kurallari PR surecine entegre edilir. Required alan ekleme, tip değiştirme ve enum daraltma breaking sayilir. Deprecation sunset tarihi spec aciklamasinda ve changelog'da yer alir. Tuketicilere email ve portal bildirimi gonderilir.

Güvenlik incelemesi

Spec'te internal endpoint'lerin yanlislikla public portalda yayinlanmamasi icin visibility kontrolu yapilir. Örnek degerlerde gerçek credential kullanılmaz. OAuth redirect URI ve scope listesi güvenlik review'dan gecer.

Ekip is akisi

API review toplantisinda spec onceliklidir. Backend ve frontend ekipleri ayni spec branch'inde çalışır. Spec merge edilmeden implementasyon merge edilmez. Bu disiplin entegrasyon hatalarini erken yakalar.