Swagger/OpenAPI Notları ve İpuçları

Giriş

OpenAPI Girişimi'nin bir parçası olan Swagger, RESTful API'ler tasarlamak, oluşturmak, belgelemek ve tüketmek için güçlü bir araç setidir. Bu özet tablo, en son ana sürüm olan OpenAPI Spesifikasyonu 3.0'ı kapsar.

Temel Yapı

Temel bir OpenAPI 3.0 belgesi aşağıdaki yapıya sahiptir:

openapi: 3.0.0
info:
  title: Örnek API
  description: İsteğe bağlı çok satırlı veya tek satırlı açıklama [CommonMark](http://commonmark.org/help/) veya HTML formatında.
  version: 0.1.9
servers:
  - url: http://api.example.com/v1
    description: İsteğe bağlı sunucu açıklaması, örn. Ana (üretim) sunucu
paths:
  /users:
    get:
      summary: Kullanıcı listesini döndürür.
      description: İsteğe bağlı genişletilmiş açıklama CommonMark veya HTML formatında.
      responses:
        '200':
          description: Kullanıcı adlarının JSON dizisi
          content:
            application/json:    
              schema:
                type: array
                items:
                  type: string

Bilgi Nesnesi

Bilgi nesnesi API meta verilerini içerir:

info:
  title: Örnek API
  description: OpenAPI kavramlarını göstermek için örnek bir API
  version: 1.0.0
  termsOfService: http://example.com/terms/
  contact:
    name: API Desteği
    url: http://www.example.com/support
    email: support@example.com
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html

Sunucular

Bir veya daha fazla API sunucusu tanımlayın:

servers:
  - url: https://development.gigantic-server.com/v1
    description: Geliştirme sunucusu
  - url: https://staging.gigantic-server.com/v1
    description: Hazırlık sunucusu
  - url: https://api.gigantic-server.com/v1
    description: Üretim sunucusu

Yollar

Yollar, API'nizin uç noktalarını ve bu uç noktalarda mevcut olan işlemleri tanımlar:

paths:
  /users:
    get:
      summary: Kullanıcı listesini döndürür.
      responses:
        '200':
          description: Başarılı yanıt
    post:
      summary: Yeni bir kullanıcı oluşturur.
      responses:
        '201':
          description: Oluşturuldu
  /users/{userId}:
    get:
      summary: ID'ye göre bir kullanıcı döndürür.
      parameters:
        - name: userId
          in: path
          required: true
          description: Döndürülecek kullanıcının ID'si.
          schema:
            type: integer
      responses:
        '200':
          description: Başarılı yanıt

Parametreler

Parametreler yol, sorgu dizesi, başlıklar ve çerezler aracılığıyla geçirilebilir:

parameters:
  - in: path
    name: userId
    required: true
    schema:
      type: integer
  - in: query
    name: limit
    schema:
      type: integer
  - in: header
    name: X-Request-ID
    schema:
      type: string
  - in: cookie
    name: session_id
    schema:
      type: string

İstek Gövdesi

POST, PUT ve PATCH işlemleri için istek gövdesini tanımlayın:

requestBody:
  required: true
  content:
    application/json:
      schema:
        type: object
        properties:
          name:
            type: string
          email:
            type: string

Yanıtlar

Her işlem için olası yanıtları tanımlayın:

responses:
  '200':
    description: Başarılı yanıt
    content:
      application/json:
        schema:
          type: array
          items:
            type: string
  '400':
    description: Hatalı istek
  '404':
    description: Kaynak bulunamadı

Şema

İstek ve yanıt yüklerini tanımlamak için JSON Şema sözcük dağarcığını kullanın:

components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        email:
          type: string
      required:
        - id
        - name

Bileşenler

API'nin farklı yönleri için yeniden kullanılabilir nesneler:

components:
  schemas:
    User: 
      type: object
      properties:
        id: 
          type: integer
        name: 
          type: string
  responses:
    NotFound:
      description: Kaynak bulunamadı
  parameters:
    skipParam:
      name: skip
      in: query
      description: atlanacak öğe sayısı
      schema:
        type: integer
  examples:
    user:
      value:
        id: 1
        name: Ahmet Yılmaz
  requestBodies:
    UserBody:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/User'
  headers:
    X-Rate-Limit:
      description: kullanıcıya saatte izin verilen çağrı sayısı
      schema:
        type: integer
  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic

Güvenlik

Güvenlik gereksinimlerini tanımlayın:

security:
  - BasicAuth: []
  - ApiKeyAuth: []
  - OAuth2:
    - read
    - write

components:
  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
    OAuth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://example.com/oauth/authorize
          tokenUrl: https://example.com/oauth/token
          scopes:
            read: Okuma erişimi verir
            write: Yazma erişimi verir

Etiketler

İşlemleri etiketlerle gruplandırın:

tags:
  - name: users
    description: Kullanıcı işlemleri
  - name: products
    description: Ürün işlemleri

paths:
  /users:
    get:
      tags:
        - users
      # ...
  /products:
    get:
      tags:
        - products
      # ...

Harici Belgeler

Harici belgelere bağlantı verin:

externalDocs:
  description: API Belgeleri
  url: https://docs.example.com