Swagger Nedir? Neden kullanılır?

Swagger Rest API geliştirmek için gerekli bir sözleşme standardı ve bu çerçevede işlev gören yardımcı araçlar sunan bir teknolojidir. Swagger sunduğu standart ve araçlarla API tasarım, geliştirme, dokümantasyon ve test aşamasında kolaylık sağlamaktadır.

Haberleşmenin en önemli aşaması sözleşmedir. Örneğin biz aramızda haberleşmek için Türkçe sözleşmesinden faydalanıyoruz. Kuralları belli. Değil Türkçe dumanla haberleşmenin bile bir sözleşmesi ve kalıbı var.

İki bilgisayar sistemini haberleştirirken sıklıkla Rest API’lerinden faydalanıyoruz. Sık kullanıyoruz fakat kendisi bir standart olmadığı için, herkesin üzerinde anlaştığı standart bir servis sözleşmesi biçimi yok ve bu durum haberleşme açısından iyi bir durum değil. Fakat Swagger OpenAPI standardını kullanarak, API’lerimizi hem insanların hem de makinelerin anlayacağı formatta ortak bir dilde paylaşabiliriz. İnsanlar Open API sözleşmelerinize bakınca servis içeriğinin ne olduğunu anlayabilir. Bunun yanında makineler için sözleşme kurallarına uyan client veya server kodu üretebiliriz. 40 üzeri dil ve uygulama platformunu destekleyen Swagger, günümüz API geliştiriminde iyi bir platform tercihi olarak karşımıza çıkmaktadır.

API geliştirmede diğer bir önemli ihtiyaç ise dokümantasyon ihtiyacıdır. Servislerinizi diğer geliştiricilere özel veya herkese açık olarak paylaştığınızda, API metotlarının ne iş gördüğü ve nasıl çalıştığı ile ilgili anlaşılır bir dokümanınız olmalıdır. API dokümanlarını el emeğiyle yazmak hem zor hem de güncel tutması imkansızdır. Bir biçimde bu dokümanların otomatik olarak üretilmesi gerekir. Swagger’in diğer bir özelliği YAML veya JSON biçiminde tutulan servis sözleşmelerinden otomatik olarak dokümantasyon oluşturabiliyor olmasıdır.

Aşağıda YAML biçiminde hazırlanmış bir Swagger API sözleşmesini görmektesiniz.

swagger: '2.0'
info:
  description: Kodedu API contract
  version: 1.0.0
  title: Kodedu API Demo
  contact:
    email: rahmanusta@kodedu.com
  license:
    name: Apache 2.0
    url: 'http://www.apache.org/licenses/LICENSE-2.0.html'
host: swagger.kodedu.com
basePath: /v1
schemes:
  - http
paths:
  /edu:
    get:
      summary: Gets edu list
      description: Gets training list in kodedu.com
      responses:
        '200':
          description: OK
          schema:
            items:
              $ref: '#/definitions/Edu'
        '400':
          description: Api Error
      produces:
        - application/json
definitions:
  Edu:
    type: object
    title: An Edu object
    properties:
      code:
        type: integer
        format: int64
      name:
        type: string
      url:
        type: string

YAML olarak yazılmış bir sözleşmeyi JSON biçiminde de sergileyebiliriz. Swagger iki formatı birden desteklemektedir.

{
  "swagger": "2.0",
  "info": {
    "description": "Kodedu API contract",
    "version": "1.0.0",
    "title": "Kodedu API Demo",
    "contact": {
      "email": "rahmanusta@kodedu.com"
    },
    "license": {
      "name": "Apache 2.0",
      "url": "http://www.apache.org/licenses/LICENSE-2.0.html"
    }
  },
  "host": "swagger.kodedu.com",
  "basePath": "/v1",
  "schemes": [
    "http"
  ],
  "paths": {
    "/edu": {
      "get": {
        "summary": "Gets edu list",
        "description": "Gets training list in kodedu.com",
        "responses": {
          "200": {
            "description": "OK",
            "schema": {
              "items": {
                "$ref": "#/definitions/Edu"
              }
            }
          },
          "400": {
            "description": "Api Error"
          }
        },
        "produces": [
          "application/json"
        ]
      }
    }
  },
  "definitions": {
    "Edu": {
      "type": "object",
      "title": "An Edu object",
      "properties": {
        "code": {
          "type": "integer",
          "format": "int64"
        },
        "name": {
          "type": "string"
        },
        "url": {
          "type": "string"
        }
      }
    }
  }
}

Yukarıdaki sözleşmelerden birini editor.swagger.io adresine yapıştırarak deneyebilirsiniz.