Python 3.9.5 Sanic OpenAPI — Part 1
Özet
Python 3.9.5, 3 Mayıs 2021 tarihinde yayınlanmıştır. Şu an için stabil çalışan en güncel versiyondur. Python Release Python 3.9.5 adresinden release info ve indirme linkleri görüntülenebilir.
Sanic, Python ile geliştirilmeye devam edilen, asenkron çalışma mantığına sahip, kurulumu ve kullanımı oldukça basit olan bir web server ve web framework’tür.
Introduction adresinden resmi web sitesine ulaşabilirsiniz. 19.06.2021 itibariyle en güncel versiyonu 21.3.4’tür. Python 3.7+ için ve Sanic Community tarafından geliştirilmektedir.
OpenAPI, Swagger olarak da bilinen bir kavramdır. RESTful API’lerine standart, dil bağımsız bir arabirim sunar. Bu arabirim üzerinden RESTful API’ler görüntülenebilir ve test edilebilir. OpenAPI Specification — Version 3.0.3 | Swagger adresinden detaylarına ulaşılabilir.
Bu yazıda Sanic’in en güncel versiyonunu kullanarak basit bir microservice yazacağız ve OpenAPI ile endpointleri görselleştireceğiz.
Kurulum
- Python Release Python 3.9.5 adresinden Python 3.9.5’i indirelim.
- Terminalden şu komutları yazalım.
- En sevdiğimiz metin editörü ile oluşturduğumuz sanic-swagger adlı projeyi açalım. Ben PyCharm kullanıyorum. Pycharm üstün özelliklere sahip bir IDE’dir.
Giriş
İlk olarak basit bir hello world app oluşturalım.
Terminal üzerinden aşağıdaki komutu çalıştıralım.
Çalıştırdıktan sonra browser’dan http://localhost:8000 adresine gidip çıktıyı görelim. Ekranda {‘hello’: ‘world’} yazacaktır.
Şimdi oluşturduğumuz hello world app’e OpenAPI’yi entegre edelim. Bunun için sanic_openapi paketini import edip, yeni bir blueprint oluşturup içine ekleyeceğiz.
Daha sonra uygulamayı çalıştıralım. http://localhost:8000/swagger/ adresine gidelim. Swagger entegrasyonunu yapmış olduk.
Bu ekrandan ilgili endpointlere tıklayıp, Try It deyip, endpointin beklediği değerleri girip endpointi çalıştırabiliriz.
Şimdi hello world app’imizi biraz daha geliştirelim. Her HTTP Metodu ile birer adet endpoint hazırlayalım ve swagger sayfasındaki değişikliklere bakalım. HTTPMethodView bize bir API class’ı oluşturmayı sağlar. Fonksiyonların isimleri HTTP Metodlarının isimleriyle eşleşmelidir.
Çalıştırıp http://localhost:8000/swagger/ adresine gidelim. Görüldüğü üzere tüm endpointlerimiz burada listelenmektedir.
Dilersek API’lerimizi sınıflandırabiliriz. Şu anki sınıf adı ‘default’. Bunu ‘bp’ yapalım. Ayrıca tüm ‘bp’ sınıfındaki endpointlerin prefixlerini değiştirelim. Yeni adres http://localhost:8000/bp olsun.
Çalıştırıldığında sınıflandırılmış halini görebiliriz.
Configuration
Hem Sanic API’mizi hem de Swagger’ı dilediğimiz şekilde konfigüre edebiliriz. Örnek kullanım aşağıdadır. Tüm konfigürasyon ayarları için Configurations — Sanic-OpenAPI 21.3.2 documentation sayfasını ziyaret edebilirsiniz.
Decorators
Swagger’da API’leri dökümante ederken kullanılabilecek çok sayıda dekoratör vardır. Dekoratörler ve açıklamaları aşağıdadır.
Summary, description ve exclude kullanarak bir örnek yapalım.
Örneğin Put endpointi aşağıdaki gibi dokümante edilmiştir. Ayrıca exclude dekoratörünü kullandığımız için options endpointi dokümanda görüntülenemeyecektir.
Consumes, produces ve response kullanarak da bir örnek yapalım. Ayrıca model oluşturmayı öğrenelim.
Yukarıda User, Test ve TestResponse adında 3 adet model oluşturduk. Post endpointine Request Body olarak Test modelini verdik, 200 kodlu response için TestResponse modelini verdik, ayrıca header ve query parameter ekledik. Son durumda döküman aşağıdaki gibi güncellendi.
Request için gereken body, parametre ve headerları isteyen ekran aşağıdaki gibi oluştu.
Sonraki yazımızda modellerin özelleştirilmesi üzerinde duracağız. Görüşmek üzere.
Kaynakça
