Swagger'ı Kullanarak Node.js API'si Nasıl Oluşturulur

API dokümantasyonu, yazılım geliştirmede, kullanıcıların API'lerle ve hizmetleriyle nasıl etkileşim kuracakları konusunda içgörüler sağlayan hayati bir bileşen olarak hizmet eder. Bu kılavuzda, etkileşimli API dokümantasyonunun otomatik olarak oluşturulmasını ve API testini kolaylaştıran, Node.js ile oluşturulmuş API'leri belgelemek için bir araç olan Swagger'dan yararlanmayı inceliyoruz.

Ek olarak, çeşitli protokollerde test ve sorunsuz işbirliğini kapsayan, gelişmiş API yönetimi için güçlü bir entegrasyon olarak Apidog'u tanıtıyoruz. Adım adım talimatlar ve içgörülerle, geliştiriciler API geliştirmeyi kolaylaştırabilir ve uygulamalarında sağlamlık ve verimlilik sağlayabilirler.

button

Swagger'da API'yi Belgelemek Üzerine Nihai Bir Kılavuz

Swagger ile geliştiriciler, basit ve sezgisel bir YAML veya JSON formatı kullanarak API uç noktalarını, istek parametrelerini, yanıt formatlarını ve kimlik doğrulama yöntemlerini tanımlayabilirler. Bu standartlaştırılmış dokümantasyon formatı, yalnızca geliştirme ekipleri arasındaki iletişimi kolaylaştırmakla kalmaz, aynı zamanda istemciler için API tüketimini de basitleştirir.

Node.js Ortamını Kurmak

Swagger ile Node.js API'mizi oluşturmaya başlamadan önce, geliştirme ortamımızın düzgün bir şekilde kurulduğundan emin olalım. Makinenizde Node.js'nin yüklü olduğundan emin olun. Node.js'yi resmi web sitesinden indirebilir ve yükleyebilirsiniz veya kurulum için npm veya yarn gibi bir paket yöneticisi kullanabilirsiniz.

Swagger Araçlarını Yüklemek

Swagger'ı kullanmaya başlamak için gerekli Swagger araçlarını yüklememiz gerekecek. Swagger ekosistemi, aşağıdakiler dahil olmak üzere API geliştirmesinin farklı aşamaları için çeşitli araçlar sağlar:

Swagger Editor: Swagger spesifikasyonlarını tasarlamak ve test etmek için web tabanlı bir editör.
Swagger UI: Swagger dokümantasyonuyla görselleştirmek ve etkileşim kurmak için kullanıcı dostu bir arayüz.
Swagger Codegen: Swagger spesifikasyonlarına göre sunucu stub'ları ve istemci kitaplıkları oluşturmak için bir araç.

Bu araçları npm veya yarn kullanarak genel olarak yükleyebilirsiniz:

npm install -g swagger-cli swagger-ui-express

API'nizi Swagger ile Tasarlamak

Geliştirme ortamı kurulduktan ve Swagger araçları yüklendikten sonra, Swagger kullanarak Node.js API'mizi tasarlamaya başlayabiliriz. İlk adım, API uç noktalarımızı, istek parametrelerimizi, yanıt şemalarımızı ve diğer ilgili ayrıntıları açıklayan bir Swagger spesifikasyon dosyası (genellikle YAML veya JSON formatında) oluşturmaktır.

İşte basit bir Todo API'si için bir Swagger spesifikasyonunun temel bir örneği:

openapi: 3.0.0
info:
  title: Todo API
  version: 1.0.0
  description: A simple Todo API
paths:
  /todos:
    get:
      summary: Get all todos
      responses:
        '200':
          description: A list of todos
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: integer
                    title:
                      type: string
                    completed:
                      type: boolean
    post:
      summary: Create a new todo
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                title:
                  type: string
                  example: Buy groceries
                completed:
                  type: boolean
                  example: false
      responses:
        '201':
          description: Created

Bu Swagger spesifikasyonunda:

info bölümünde API başlığını, sürümünü ve açıklamasını tanımlıyoruz.
Tüm yapılacakları (GET) almak ve yeni bir yapılacak oluşturmak (POST) için iki uç nokta (/todos) belirtiyoruz.
Her uç nokta bir özet, istek gövdesi (varsa) ve yanıt şeması içerir.

Swagger'da API'leri Test Etmek

API dokümantasyonumuzu tamamladıktan sonra, Swagger dokümantasyonunu görüntüleyebilmeli ve API'lerimizi test etmek için kullanabilmeliyiz. Daha önce belirtilen adımları izlediyseniz, aşağıda açıklanan benzer bir arayüz görmelisiniz. Dokümantasyonumuz /docs rotasında sunulacaktır.

Bazı istekler yapmak ve sonuçları gözlemlemek için Swagger belge UI'sini kullanacağız.

Kullanıcı oluşturma:

Gönderi oluşturma:

Yukarıdaki örneklerden görebileceğimiz gibi, API'mizi test etmek için Swagger belgesini kullanabilir, veritabanında veri oluşturmamıza, okumamıza ve değiştirmemize olanak tanırız. Bu, API'nin anlaşılmasını ve entegre edilmesini kolaylaştırmaya yardımcı olur.

Bu örnekleri takiben, kullanıcıları veya gönderileri güncellemek için PUT, kullanıcıları veya gönderileri okumak için GET ve veritabanından kaldırmak için DELETE gibi diğer istek yöntemlerini test etmeye devam edebiliriz.

Sonuç olarak, API dokümantasyonunun, işbirliğini kolaylaştıran ve sorunsuz kullanıcı deneyimleri sağlayan yazılım geliştirme yaşam döngüsünde önemli bir rol oynadığı açıktır. Swagger'ın avantajları, diğerlerinin yanı sıra şunları içerir:

API dokümantasyonunun hem sunucular hem de istemcilerle senkronizasyonu.
REST API dokümantasyonunun oluşturulmasını ve etkileşimini kolaylaştırma. Swagger UI çerçevesini kullanmak, parametrelere yönelik API yanıtları hakkında kapsamlı bilgiler sağlar.
JSON ve XML formatlarında yanıtların sağlanması.
Çeşitli teknolojilerde uygulama çok yönlülüğü.

Apidog ile API Dokümantasyonunu Yönetmek

API'leri Swagger ile yönetmek bazen hantal olabilir ve ekipler arasında işbirliğinden yoksun olabilir, bu nedenle bunun yerine Apidog kullanmanızı öneririm.

Apidog, Postman'e kıyasla daha sağlam bir API test aracıdır. HTTP(s), WebSocket, Socket, gRPC gibi protokoller için hata ayıklama arayüzlerini destekler ve IDEA eklentileriyle entegre olur.

button

API'yi geliştirdikten sonra, Apidog'un IDEA eklentisiyle birden fazla platformda kolayca API dokümantasyonu oluşturabilir, test ve bakımı çok uygun hale getirebilirsiniz.

Swagger'ı JSON'a Aktarmak

Aşağıda gösterildiği gibi, Swagger belgesini bir JSON dosyası olarak dışa aktarmak için "JSON olarak dönüştür ve kaydet" seçeneğini seçin.

Swagger Dosyalarını Apidog'a İçe Aktarmak

Apidog'u açın, bir proje oluşturun, ardından "Proje Ayarları->Veri İçe Aktar->OpenAPI/Swagger->Dosya İçe Aktar" bölümüne gidin ve daha önce dışa aktardığınız Swagger formatlı JSON dosyasını içe aktarın.

İçe aktarırken, bir önizleme olacaktır ve tümünü veya seçerek API'yi içe aktarmayı seçebilirsiniz. İçe aktarma başarılı olduktan sonra, API'yi test etmek için bir ortam seçebilirsiniz.

Daha fazla bilgi edinmek için bu bağlantıyı kontrol edin: https://apidog.com/help/importing-and-exporting-data/importing-data/importing-openapi-specification