Swagger ile Restful API Dökümanı Oluşturma

Standard

Merhaba;

Restful API oluştururken, kod mimarisini ve işlevlerini açıklamakta kullanılan swagger harika bir arayüze ve kaliteli dokümana sahip güzel bir araç.

Sitesi:

https://swagger.io/

Şu bir gerçek ki geliştiricilerin sıkıntılarından birisi de yazılan kodu  doküman haline getirmektir. İşte bu iş için adamlar düşünmüş “bir sistem oluşturalım, geliştirici isterse önce dokümanı yazsın, oradan aldığı iskeleti IDE’ye aktarıp oradan dokümana uygun yapının gövdesini yazsın, isterse de doctstring’ler üzerinden şemayı biz oluşturalım” demişler ve Swagger’ı çıkartmışlar.

Swagger entegrasyonu için buradan kullanılabilecek kütüphanelere ulaşabilirsiniz;
https://swagger.io/open-source-integrations/

Peki nasıl kullanabiliriz?

Bu konuda 2 yöntem mevcut,

  1. Swagger online editör vasıtasıyla mimariyi oluşturup, JSON ya da YAML biçiminde almak.
  2. Swaggerhub üzerinden mimariyi oluşturmak ya da Hub’daki mimarilerden bir tanesini seçip direk kullanmak.

Örnek bir kullanımla açıklamak daha iyi olacak, swagger editörü açtığınız zaman size şablonlar sunulmakta, ister bu şablonları kullanabilirsiniz, isterseniz de online editörde hali hazırda varolan şablonu özelleştirerek kullanabilirsiniz. Ben online editör üzerinden ilerleyeceğim. Online editörün sayfasına giriyoruz;

http://editor.swagger.io/#

Karşımıza hazır şablon sunulmuş oluyor, ilk kısımda projenin tanımı ve içeriğine dair bilgi kısmı bulunuyor, sol tarafta yazdığınız şemanın sağda gösterimi interaktif şekilde sunulmakta, hatalı yazdığınızda ise hata mesajları verilmekte.

swagger: "2.0"
info:
 description: "This is a sample server Petstore server. You can find out more about Swagger at [http://swagger.io](http://swagger.io) or on [irc.freenode.net, #swagger](http://swagger.io/irc/). For this sample, you can use the api key `special-key` to test the authorization filters."
 version: "1.0.0"
 title: "Swagger Petstore" 
 termsOfService: "http://swagger.io/terms/"
 contact:
 email: "apiteam@swagger.io"
 license:
 name: "Apache 2.0"
 url: "http://www.apache.org/licenses/LICENSE-2.0.html"
host: "petstore.swagger.io"
basePath: "/v2"
tags:
- name: "pet"
 description: "Everything about your Pets"
 externalDocs:
 description: "Find out more"
 url: "http://swagger.io"
- name: "store"
 description: "Access to Petstore orders"
- name: "user"
 description: "Operations about user"
 externalDocs:
 description: "Find out more about our store"
 url: "http://swagger.io"
schemes:
- "http"

Buradan sonraki kısımda, “paths” kısmında API’nin hangi path’lerden nasıl tetikleneceğini açıklamaya başlıyorsunuz. Editörde varsayılan olarak “/pet” geldiğinde nasıl tepki vereceğii açıklanmış durumda.

 /pet:
 post:
 tags:
 - "pet"
 summary: "Add a new pet to the store"
 description: ""
 operationId: "addPet"
 consumes:
 - "application/json"
 - "application/xml"
 produces:
 - "application/xml"
 - "application/json"
 parameters:
 - in: "body"
 name: "body"
 description: "Pet object that needs to be added to the store"
 required: true
 schema:
 $ref: "#/definitions/Pet"
 responses:
 405:
 description: "Invalid input"
 security:
 - petstore_auth:
 - "write:pets"
 - "read:pets"

Swagger kullanımıyla alakalı dökümana buradan ulaşabilirsiniz;

Swagger (OpenAPI) Specification

Bir Cevap Yazın

E-posta hesabınız yayımlanmayacak. Gerekli alanlar * ile işaretlenmişlerdir