Python ile OpenAPI Dökümanı Oluşturma: PySwagger Rehberi

Kapsamlı ve doğru API dokümantasyonu oluşturmak, yazılım geliştirmenin kritik ama genellikle zahmetli bir parçasıdır. OpenAPI Spesifikasyonu (eskiden Swagger olarak bilinir), RESTful API'leri tanımlamak için endüstri standardı olarak ortaya çıkmıştır. Kaynak koduna, dokümantasyona veya ağ trafiği incelemesine erişim olmadan hem insanların hem de bilgisayarların bir hizmetin yeteneklerini keşfetmesine ve anlamasına olanak tanıyan makine tarafından okunabilir bir format sağlar.¹

Birçok framework, kod açıklamalarından (docstring'ler gibi) OpenAPI spesifikasyonları oluşturmak için eklentiler sunarken, spesifikasyonun oluşturulması üzerinde daha doğrudan, programatik kontrole ihtiyaç duyabileceğiniz senaryolar vardır. Bu, eski bir sistemle, standart olmayan bir framework ile çalışıyor olmanız veya birden fazla mikro hizmetten oluşan bir API için bir spesifikasyon oluşturmanız gerekmesinden kaynaklanabilir.

İşte burada pyswagger devreye girer. OpenAPI için bir araç seti olarak işlev gören güçlü bir Python kütüphanesidir. Genellikle bir OpenAPI spesifikasyonu tarafından tanımlanan hizmetleri kullanmak için bir API istemcisi olarak kullanılsa da, gerçek gücü, bir spesifikasyonu programatik olarak oluşturmanıza, manipüle etmenize ve doğrulamanıza olanak tanıyan nesne modelinde yatar.

Bu kapsamlı eğitimde, Flask ile oluşturulmuş basit bir Python web uygulaması için tam bir OpenAPI 3.0 spesifikasyonunu manuel olarak, ancak otomatik bir şekilde oluşturmak için pyswagger kullanma sürecini adım adım inceleyeceğiz. Spesifikasyonu sıfırdan, parça parça oluşturarak, pyswagger nesnelerinin OpenAPI standardının bileşenleriyle nasıl doğrudan eşleştiğini göstereceğiz. Sonunda, yalnızca oluşturulmuş bir openapi.json dosyasına değil, aynı zamanda uygulamanızdan doğrudan sunulan canlı, etkileşimli bir dokümantasyon kullanıcı arayüzüne sahip olacaksınız.

💡

güzel API Dokümantasyonu oluşturan harika bir API Test Aracı mı istiyorsunuz?

Geliştirici Ekibinizin maksimum üretkenlikle birlikte çalışması için entegre, Hepsi Bir Arada bir platform mu istiyorsunuz?

Apidog tüm taleplerinizi karşılar ve Postman'ı çok daha uygun bir fiyata değiştirir!

düğme

Bölüm 1: Proje Ortamını Kurma

Spesifikasyonumuzu oluşturmaya başlamadan önce uygun bir geliştirme ortamı kurmamız gerekiyor. Bu, bağımlılıklarımızı yönetmek için izole bir Python ortamı oluşturmayı ve gerekli kütüphaneleri yüklemeyi içerir.

Çalışma Alanınızı Oluşturma ⚙️

İlk olarak projemiz için bir dizin oluşturalım. Terminalinizi veya komut istemini açın ve aşağıdaki komutları çalıştırın:Bash

# Projemiz için yeni bir dizin oluştur
mkdir pyswagger-tutorial
cd pyswagger-tutorial

# Bir Python sanal ortamı oluştur
# macOS/Linux üzerinde
python3 -m venv venv
# Windows üzerinde
python -m venv venv

Sanal ortam, bir Python kurulumu ve bir dizi destekleyici dosya içeren, kendi içinde kapalı bir dizin ağacıdır. Sanal ortam kullanmak, bu proje için yüklediğimiz paketlerin, diğer projeler için yüklenen paketlerle çakışmamasını sağlar.

Şimdi sanal ortamı etkinleştirin:Bash

# macOS/Linux üzerinde
source venv/bin/activate

# Windows üzerinde
.\venv\Scripts\activate

Etkinleştirildikten sonra, terminal isteminiz sanal ortamın adını (örneğin, (venv)) gösterecek şekilde değişmeli, bu da artık onun içinde çalıştığınızı belirtir.

Gerekli Kütüphaneleri Yükleme

Ortamımız etkin durumdayken, bu eğitim için ihtiyaç duyacağımız Python kütüphanelerini yükleyebiliriz. Spesifikasyonu oluşturmak için pyswagger'ın kendisine, basit web API'mizi oluşturmak için Flask'a ve pyswagger'ın YAML işlemleri için kullandığı PyYAML'a ihtiyacımız var.Bash

pip install "pyswagger[utils]" Flask PyYAML

pyswagger yüklenirken kullanılan [utils] kısmı iyi bir uygulamadır, çünkü daha sonra oluşturduğumuz spesifikasyonun doğruluğunu kontrol etmek için kullanacağımız bir doğrulayıcı gibi faydalı yardımcı programlar içerir.

İyi bir proje yönetimi için, bağımlılıklarınızı bir requirements.txt dosyasına sabitlemek akıllıca olacaktır.Bash

pip freeze > requirements.txt

requirements.txt dosyanız artık kütüphaneleri ve bunların belirli sürümlerini içerecek ve projenizin başkaları tarafından kolayca yeniden üretilebilir olmasını sağlayacaktır.

Temel Flask Uygulamasını Oluşturma

Şimdi minimal bir Flask uygulaması oluşturalım. Bu, belgeleyeceğimiz API'nin temelini oluşturacaktır.

Proje dizininizde app.py adında yeni bir dosya oluşturun ve aşağıdaki kodu ekleyin:Python

# app.py

from flask import Flask, jsonify

# Flask uygulamasını başlat
app = Flask(__name__)

@app.route("/")
def index():
    """ Uygulamanın çalışıp çalışmadığını kontrol etmek için basit bir uç nokta. """
    return jsonify({"message": "API is up and running!"})

if __name__ == "__main__":
    # Flask uygulamasını http://127.0.0.1:5000 üzerinde çalıştırır
    app.run(debug=True)

Bu kod, tek bir uç noktaya sahip çok basit bir web sunucusu kurar. Çalıştırmak için sanal ortamınızın hala etkin olduğundan emin olun ve terminalinizde aşağıdaki komutu çalıştırın:Bash

python app.py

Sunucunun çalıştığını belirten şöyle bir çıktı görmelisiniz:

 * Serving Flask app 'app'
 * Debug mode: on
 * Running on http://127.0.0.1:5000 (Press CTRL+C to quit)

Artık web tarayıcınızı açabilir veya curl gibi bir araç kullanarak http://127.0.0.1:5000 adresini ziyaret edebilirsiniz. Şu JSON yanıtını görmelisiniz: {"message": "API is up and running!"}.

Temel ortamımız ve uygulama iskeletimiz hazır olduğuna göre, artık pyswagger'ın temel kavramlarına dalabiliriz.

Bölüm 2: `pyswagger` Nesne Modelini Anlama

Bir spesifikasyon oluşturmak için pyswagger'ı etkili bir şekilde kullanmak için öncelikle nesne modelinin bir OpenAPI belgesinin yapısına nasıl karşılık geldiğini anlamanız gerekir. Bir OpenAPI spesifikasyonu esasen belirli bir şemaya sahip büyük bir JSON veya YAML nesnesidir. pyswagger, bu şemayı yansıtan Python sınıfları ve nesneleri sağlayarak spesifikasyonu daha sezgisel, nesne yönelimli bir şekilde oluşturmanıza olanak tanır.

OpenAPI 3.0 Spesifikasyonunun Temel Kavramları 📜

Bir OpenAPI 3.0 belgesinin birkaç temel üst düzey alanı vardır:

openapi: OpenAPI Spesifikasyon sürümünü belirten bir dize (örneğin, '3.0.0').
info: API hakkında meta veri sağlayan bir nesne. Bu, title, version, description ve iletişim bilgilerini içerir.
servers: API için temel URL'leri tanımlayan sunucu nesneleri dizisi.
paths: En önemli alan. Bu nesne, tüm mevcut API uç noktalarını (yollar) ve bunlar üzerinde gerçekleştirilebilecek HTTP işlemlerini (GET, POST, PUT, DELETE vb.) tutar.
components: Spesifikasyonun farklı bölümleri için bir dizi yeniden kullanılabilir nesneyi tutan bir nesne. Bu, spesifikasyonunuzu DRY (Kendinizi Tekrar Etmeyin) tutmak için anahtardır. Yeniden kullanılabilir schemas (veri modelleri), responses, parameters, examples ve daha fazlasını tanımlayabilirsiniz.

OpenAPI'yi `pyswagger` Nesneleriyle Eşleme

pyswagger, bu OpenAPI kavramlarından Python nesnelerine temiz bir eşleme sağlar. Kullanacağımız birincil olanları keşfedelim.

pyswagger'daki merkezi nesne App'tir. Bir App örneğini OpenAPI belgenizin kökü olarak düşünebilirsiniz.Python

from pyswagger import App\n\n# Spesifikasyon belgesinin kökü\n# Bir sürümle başlatıyoruz, ancak bir URL'den veya dosyadan da yüklenebilir\nroot_app = App(version='3.0.0')\n

App nesnenize sahip olduğunuzda, doğrudan OpenAPI alanlarına karşılık gelen niteliklerini doldurmaya başlayabilirsiniz. pyswagger, akıcı ve okunabilir bir sözdizimi sağlayan bir builder deseni kullanır.

Bilgi ve Sunucular

info ve servers bölümlerini doldurmak kolaydır.Python

# 'info' nesnesini doldurma\nroot_app.info.title = "Kullanıcı API'si"\nroot_app.info.version = "1.0.0"\nroot_app.info.description = "pyswagger eğitimi için kullanıcıları yönetmek için basit bir API."\n\n# 'servers' dizisini doldurma\n# Bir Sunucu nesnesi oluşturup ekliyorsunuz\nserver = root_app.prepare_obj('Server', {'url': 'http://127.0.0.1:5000', 'description': 'Yerel geliştirme sunucusu'})\nroot_app.servers.append(server)\n

Yollar ve İşlemler

Yollar App nesnesi üzerinde tanımlanır. Yeni yollar ekler ve ardından bunların içinde işlemleri (HTTP yöntemleri) tanımlarsınız. Her işlem, summary, description, parameters, bir requestBody ve responses gibi ayrıntılarla yapılandırılır.Python

# Bir yol ve bir işlem tanımlama\n# Bu hiçbir şeyi yürütmez; sadece nesne yapısını oluşturur.\npath_item = root_app.define_path('/users')\nget_op = path_item.define_op('get')\nget_op.summary = "Tüm kullanıcıların listesini al"\n

Bileşenler: Şemalar, Parametreler ve Yanıtlar

İyi yapılandırılmış bir OpenAPI spesifikasyonunun gerçek gücü, yeniden kullanılabilir bileşenlerden gelir. Bir "Kullanıcı" nesnesinin yapısını bir yanıtta her göründüğünde tanımlamak yerine, onu components/schemas içinde bir kez tanımlar ve ardından bir $ref işaretçisi kullanarak referans verirsiniz. pyswagger bunu zarif bir şekilde ele alır.

Schema: Bir Schema nesnesi bir veri modelini tanımlar. Türünü (object, string, integer) ve özelliklerini belirtebilirsiniz.Python

# Bir Kullanıcı için Şema nesnesi hazırlama\nuser_schema = root_app.prepare_obj('Schema', {\n    'type': 'object',\n    'properties': {\n        'id': {'type': 'integer', 'format': 'int64', 'description': 'Kullanıcının benzersiz tanımlayıcısı.'},\n        'username': {'type': 'string', 'description': 'Kullanıcının seçtiği kullanıcı adı.'},\n        'email': {'type': 'string', 'format': 'email', 'description': 'Kullanıcının e-posta adresi.'}\n    },\n    'required': ['id', 'username', 'email']\n})\n\n# Yeniden kullanılabilir bileşenlere ekle\nroot_app.components.schemas['User'] = user_schema\n

Parameter: Bir Parameter nesnesi tek bir işlem parametresini tanımlar. Adını, bulunduğu yeri (in: 'path', 'query', 'header' veya 'cookie') ve şemasını belirtirsiniz.Python

# Yoldaki bir kullanıcı kimliği için Parametre nesnesi hazırlama\nuser_id_param = root_app.prepare_obj('Parameter', {\n    'name': 'user_id',\n    'in': 'path',\n    'description': 'Alınacak kullanıcının kimliği',\n    'required': True,\n    'schema': {'type': 'integer'}\n})\n

Response: Bir Response nesnesi belirli bir HTTP durum kodu için bir yanıtın yapısını tanımlar. Bir description ve medya türünü (örneğin, application/json) ve şemasını belirten content içerir.Python

# Tek bir kullanıcı döndüren 200 OK yanıtı için Yanıt nesnesi hazırlama\n# Yeniden kullanılabilir Kullanıcı şemamıza işaret etmek için '$ref' kullanımına dikkat edin\nok_user_response = root_app.prepare_obj('Response', {\n    'description': 'Kullanıcının başarıyla alınması',\n    'content': {\n        'application/json': {\n            'schema': {'$ref': '#/components/schemas/User'}\n        }\n    }\n})\n

Bu eşlemeyi anlamak, spesifikasyonunuzu oluşturmanın anahtarıdır. Esasen, pyswagger'ın daha sonra geçerli bir OpenAPI JSON veya YAML dosyasına serileştireceği bir Python nesne grafiği oluşturuyorsunuz.

Bölüm 3: Flask ile Basit Bir API Oluşturma

Dokümantasyon çalışmamızı pratik hale getirmek için belgeleyecek gerçek bir API'ye ihtiyacımız var. Bölüm 1'deki basit Flask uygulamamızı, bir kullanıcı listesini yönetmek için minimal bir REST API'sine genişleteceğiz. Bu API, pyswagger ile tanımlayacağımız "doğruluk kaynağı" olarak hizmet verecektir.

Basit Bir "Kullanıcı" API'si Tasarlama 📝

Yaygın CRUD (Oluşturma, Okuma, Güncelleme, Silme) işlemlerini temsil eden dört temel uç nokta uygulayacağız:

GET /users: Tüm kullanıcıların listesini al.
POST /users: Yeni bir kullanıcı oluştur.
GET /