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: stringYAML 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.
Umarım faydalı olur. Tekrar görüşmek dileğiyle.
The post Swagger Nedir? Neden kullanılır? appeared first on KodEdu.