FastAPI Uygulamalarında Swagger ve Redoc ile API Dokümantasyonu

by
with no comment
TeknolojiYazılım Geliştirme

FastAPI Uygulamalarında Swagger ve Redoc ile API Dokümantasyonu

Günümüzde API’ler, modern yazılım mimarilerinin temel taşlarından biridir. Uygulamalar arasındaki veri alışverişini kolaylaştıran API’ler, geliştirme süreçlerini hızlandırır ve farklı sistemlerin entegrasyonunu mümkün kılar. Ancak, API’lerin etkin bir şekilde kullanılabilmesi için doğru ve anlaşılır bir şekilde dokümante edilmesi gerekmektedir. FastAPI, modern ve yüksek performanslı API’ler oluşturmak için popüler bir Python framework’üdür. FastAPI, otomatik API dokümantasyonu oluşturma konusunda da güçlü araçlar sunar: Swagger UI ve Redoc.

İçindekiler

FastAPI’ye Giriş

FastAPI, Python 3.6+ ile geliştirilen, modern ve hızlı API’ler oluşturmak için tasarlanmış bir web framework’üdür. Asenkron programlama, otomatik veri doğrulama ve serileştirme gibi özellikleri sayesinde geliştirme sürecini hızlandırır. Ayrıca, OpenAPI (eski adıyla Swagger) ve JSON Schema standartlarına uygun otomatik dokümantasyon oluşturma yeteneği ile öne çıkar. FastAPI’nin basit sözdizimi ve zengin özellik seti, onu hem yeni başlayanlar hem de deneyimli geliştiriciler için ideal bir seçenek haline getirir.

API Dokümantasyonunun Önemi

API dokümantasyonu, bir API’nin nasıl çalıştığını, hangi endpoint’leri sunduğunu, hangi parametreleri kabul ettiğini ve hangi veri formatlarını kullandığını açıklayan bir kılavuzdur. İyi bir API dokümantasyonu, geliştiricilerin API’yi kolayca anlamasını ve kullanmasını sağlar. Eksik veya yanlış dokümantasyon, geliştirme sürecini yavaşlatabilir, hatalara yol açabilir ve API’nin kullanımını zorlaştırabilir. API dokümantasyonu, API’nin sürdürülebilirliği ve yaygın kullanımı için kritik öneme sahiptir.

Swagger UI Nedir?

Swagger UI, OpenAPI spesifikasyonuna uygun olarak oluşturulmuş API dokümantasyonunu görselleştiren bir araçtır. Swagger UI, API endpoint’lerini, parametrelerini, veri tiplerini ve örnek istek-cevap çiftlerini interaktif bir arayüzde sunar. Geliştiriciler, Swagger UI üzerinden API endpoint’lerini test edebilir, istek gönderebilir ve cevapları görüntüleyebilir. Swagger UI, API dokümantasyonunu anlaşılır ve etkileşimli hale getirerek geliştirme sürecini kolaylaştırır.

Swagger UI FastAPI’de Nasıl Kullanılır?

FastAPI, Swagger UI’yi otomatik olarak entegre eder. FastAPI uygulamanızda herhangi bir endpoint tanımladığınızda, Swagger UI bu endpoint’leri otomatik olarak algılar ve dokümantasyonunu oluşturur. Swagger UI’ye erişmek için, uygulamanızın ana dizinine /docs yolunu eklemeniz yeterlidir. Örneğin, uygulamanız http://localhost:8000 adresinde çalışıyorsa, Swagger UI’ye http://localhost:8000/docs adresinden erişebilirsiniz.

Swagger UI’yi özelleştirmek için FastAPI’nin FastAPI sınıfının argümanlarını kullanabilirsiniz. Örneğin, Swagger UI’nin başlığını, açıklamasını ve sürüm numarasını değiştirebilirsiniz.


from fastapi import FastAPI

app = FastAPI(
 title="Örnek API",
 description="Bu API, örnek bir uygulamayı temsil eder",
 version="1.0.0",
)

@app.get("/")
async def read_root():
 return {"message": "Merhaba Dünya"}

Redoc Nedir?

Redoc, OpenAPI spesifikasyonuna uygun olarak oluşturulmuş API dokümantasyonunu görüntülemek için kullanılan bir diğer araçtır. Swagger UI’ye benzer şekilde, Redoc da API endpoint’lerini, parametrelerini ve veri tiplerini görüntüler. Ancak, Redoc daha sade ve okunabilir bir arayüz sunar. Redoc, özellikle büyük ve karmaşık API’ler için daha uygun olabilir.

Redoc FastAPI’de Nasıl Kullanılır?

FastAPI, Redoc’u da otomatik olarak entegre eder. Redoc’a erişmek için, uygulamanızın ana dizinine /redoc yolunu eklemeniz yeterlidir. Örneğin, uygulamanız http://localhost:8000 adresinde çalışıyorsa, Redoc’a http://localhost:8000/redoc adresinden erişebilirsiniz.

Redoc’u özelleştirmek için FastAPI’nin FastAPI sınıfının argümanlarını kullanabilirsiniz. Örneğin, Redoc’un başlığını, açıklamasını ve sürüm numarasını değiştirebilirsiniz.

Swagger ve Redoc Arasındaki Farklar

Swagger UI ve Redoc, her ikisi de OpenAPI spesifikasyonuna uygun API dokümantasyonunu görüntülemek için kullanılan araçlardır. Ancak, aralarında bazı önemli farklılıklar bulunmaktadır:

  • Arayüz: Swagger UI, daha interaktif ve kullanıcı dostu bir arayüze sahiptir. Redoc ise daha sade ve okunabilir bir arayüz sunar.
  • Özellikler: Swagger UI, API endpoint’lerini test etme ve istek gönderme gibi ek özellikler sunar. Redoc ise sadece dokümantasyonu görüntülemeye odaklanır.
  • Performans: Redoc, genellikle Swagger UI’den daha hızlıdır, özellikle büyük API’ler için.

Hangi aracın kullanılacağı, projenin gereksinimlerine ve geliştiricilerin tercihlerine bağlıdır.

API Dokümantasyonunu Özelleştirme

FastAPI, API dokümantasyonunu özelleştirmek için çeşitli seçenekler sunar. Örneğin, endpoint’lerin açıklamalarını, örnek istek-cevap çiftlerini ve veri tiplerini belirtebilirsiniz. Bu, API dokümantasyonunu daha anlaşılır ve kullanışlı hale getirir.

Endpoint’lerin açıklamalarını belirtmek için, @app.get(), @app.post(), @app.put(), @app.delete() gibi dekoratörlerin description argümanını kullanabilirsiniz.


from fastapi import FastAPI

app = FastAPI()

@app.get("/items/{item_id}", description="Belirli bir öğeyi getirir")
async def read_item(item_id: int):
 return {"item_id": item_id}

Örnek istek-cevap çiftlerini belirtmek için, Pydantic modellerini kullanabilirsiniz. Pydantic modelleri, veri doğrulama ve serileştirme için kullanılan Python sınıflarıdır. FastAPI, Pydantic modellerini otomatik olarak algılar ve API dokümantasyonunda görüntüler.


from fastapi import FastAPI
from pydantic import BaseModel

class Item(BaseModel):
 name: str
 description: str = None
 price: float
 tax: float = None

app = FastAPI()

@app.post("/items/")
async def create_item(item: Item):
 return item

Güvenlik ve Kimlik Doğrulama Dokümantasyonu

API’nizin güvenliğini sağlamak için, güvenlik ve kimlik doğrulama mekanizmalarını doğru bir şekilde dokümante etmeniz önemlidir. FastAPI, OpenAPI spesifikasyonuna uygun olarak güvenlik ve kimlik doğrulama bilgilerini dokümante etmenize olanak tanır.

Örneğin, API anahtarı (API key) kimlik doğrulaması kullanıyorsanız, API anahtarının nasıl alınacağını ve nasıl kullanılacağını dokümantasyonda belirtmelisiniz.

Sonuç

FastAPI, Swagger UI ve Redoc gibi güçlü araçlar sayesinde API dokümantasyonunu otomatik olarak oluşturmayı ve yönetmeyi kolaylaştırır. Doğru ve anlaşılır API dokümantasyonu, geliştirme sürecini hızlandırır, hataları azaltır ve API’nin kullanımını yaygınlaştırır. FastAPI projelerinizde Swagger UI ve Redoc’u kullanarak API dokümantasyonunuzu iyileştirebilir ve daha başarılı API’ler geliştirebilirsiniz.

Leave A Comment

Your email address will not be published. Required fields are marked *