Dokumentasi Otomatis FastAPI

FastAPI, secara default, menyediakan dukungan out-of-the-box untuk dua alat paling kuat dalam dokumentasi API otomatis - Swagger UI dan ReDoc. Kedua alat ini menginterpretasikan spesifikasi OpenAPI yang dihasilkan oleh FastAPI dari kode Anda, memberikan antarmuka yang ramah pengembang yang dapat digunakan untuk memahami cara berinteraksi dengan API Anda.

Swagger UI

Swagger UI adalah alat populer untuk menghasilkan dokumentasi API yang interaktif. Dengan Swagger UI, pengembang dapat dengan mudah menjelajahi semua endpoint yang berbeda dari API Anda, beserta detail terkait seperti metode HTTP, parameter, body permintaan, dan respons.

Untuk mengakses Swagger UI dalam aplikasi FastAPI, Anda hanya perlu navigasi ke endpoint /docs pada server FastAPI yang sedang berjalan. Misalnya, jika aplikasi Anda berjalan secara lokal pada port 8000, Anda akan pergi ke http://localhost:8000/docs.

Swagger UI menyediakan antarmuka intuitif di mana pengembang tidak hanya dapat melihat detail API Anda, tetapi juga berinteraksi dengannya. Interaksi ini difasilitasi oleh tombol "Try it out", yang memungkinkan pengembang untuk membuat permintaan ke API Anda langsung dari browser dan melihat respons secara real-time.

ReDoc

ReDoc adalah alat lain untuk menghasilkan dokumentasi API yang indah, mudah dibaca, dan interaktif. Sementara Swagger UI fokus pada interaktivitas, ReDoc menonjol dalam menyajikan tata letak tiga panel yang bersih dengan fokus pada kejelasan dan keterbacaan.

Untuk mengakses antarmuka ReDoc, Anda navigasi ke endpoint /redoc pada server FastAPI yang sedang berjalan. Misalnya, jika aplikasi Anda berjalan secara lokal pada port 8000, Anda akan pergi ke http://localhost:8000/redoc.

ReDoc menyajikan tampilan yang lebih minimalis dan linear dari endpoint API Anda, yang mungkin lebih mudah dinavigasi oleh beberapa pengembang. Ini masih menyajikan semua detail penting seperti endpoint, metode, parameter, dan respons, tetapi dengan cara yang lebih efisien. Namun, berbeda dengan Swagger UI, ReDoc tidak menawarkan opsi untuk berinteraksi dengan API secara langsung dari dokumentasi.

Menambahkan Metadata ke API Anda

Metadata dalam API Anda pada dasarnya adalah data tentang API Anda. Ini memberikan detail kontekstual dan informasi deskriptif tentang fungsionalitas API Anda. FastAPI memungkinkan Anda dengan mudah mendefinisikan metadata untuk API Anda, dan metadata ini akan disertakan dalam skema OpenAPI yang dihasilkan, sehingga terlihat dalam dokumentasi API otomatis.

Mendefinisikan Metadata API

Anda dapat mendefinisikan metadata untuk aplikasi FastAPI Anda saat membuat instance dari kelas FastAPI. Berikut adalah contoh:

from fastapi import FastAPI

app = FastAPI(
    title="My Super API",
    description="This is a very custom API for our organization",
    version="2.5.0",
)

Dalam contoh ini, metadata mencakup judul API, deskripsi, dan versi. Informasi ini akan muncul di bagian atas dokumentasi API Anda baik dalam Swagger UI maupun ReDoc.

Menambahkan Metadata ke Rute API

FastAPI juga memungkinkan Anda untuk menambahkan metadata ke setiap rute API secara individu. Hal ini dapat dilakukan menggunakan parameter tags pada dekorator rute FastAPI, yang mengelompokkan rute-rute terkait dalam dokumentasi.

@app.get("/items/", tags=["items"])
async def read_items():
    return [{"name": "Item 1"}, {"name": "Item 2"}]

@app.get("/users/", tags=["users"])
async def read_users():
    return [{"username": "user1"}, {"username": "user2"}]

Dalam contoh ini, rute /items/ dan /users/ dikelompokkan dalam tag "items" dan "users" masing-masing. Dalam dokumentasi yang dihasilkan, endpoint akan dikelompokkan berdasarkan tag tersebut, sehingga memudahkan navigasi dalam API.

Menambahkan Deskripsi ke Rute API

Anda dapat menambahkan deskripsi ke rute-rute Anda menggunakan docstring. Baris pertama dalam docstring digunakan sebagai ringkasan, dan baris-baris berikutnya digunakan sebagai deskripsi.

@app.get("/items/{item_id}")
async def read_item(item_id: str):
    """
    Get a specific item by ID.

    - **item_id**: ID of the item to get
    """
    return {"item_id": item_id}

Dalam contoh ini, ringkasan ("Get a specific item by ID.") dan deskripsi ("- **item_id**: ID of the item to get") akan disertakan dalam dokumentasi API untuk rute /items/{item_id}.

Mendokumentasikan Model Respons

FastAPI menggunakan model Pydantic untuk mendefinisikan struktur data respons. Model-model ini memberikan cara untuk mendefinisikan keluaran yang diharapkan dari endpoint API Anda, dan secara otomatis menghasilkan definisi JSON Schema untuk dokumentasi API Anda.

Penggunaan Dasar Model Respons

Untuk menentukan model respons untuk sebuah rute, Anda dapat menggunakan parameter response_model pada dekorator rute. Contoh berikut menjelaskan konsep ini:

from fastapi import FastAPI
from pydantic import BaseModel

class Item(BaseModel):
    name: str
    price: float

app = FastAPI()

@app.get("/items/{item_id}", response_model=Item)
async def read_item(item_id: str):
    # implementation omitted
    pass

Dalam contoh ini, parameter response_model menentukan bahwa rute /items/{item_id} akan mengembalikan sebuah instansi model Item. FastAPI akan menggunakan informasi ini untuk memvalidasi data respons, mengubahnya menjadi JSON, dan menyertakannya dalam skema OpenAPI untuk API Anda.

Menambahkan Deskripsi ke Model Respons

Anda dapat menambahkan deskripsi untuk model respons dengan menggunakan parameter responses pada dekorator rute. Parameter ini menerima sebuah kamus di mana kunci-kunci adalah kode status HTTP, dan nilainya adalah kamus yang berisi deskripsi dan model untuk respons tersebut.

@app.get("/items/{item_id}", responses={200: {"model": Item, "description": "The requested item"}})
async def read_item(item_id: str):
    # implementation omitted
    pass

Dalam contoh ini, parameter responses digunakan untuk menentukan deskripsi ("The requested item") untuk respons dengan kode status 200 yang menggunakan model Item. Deskripsi ini akan terlihat dalam dokumentasi API.

Mendokumentasikan Respons yang Berbeda

FastAPI memungkinkan Anda untuk menentukan respons yang berbeda menggunakan parameter responses. Anda dapat menentukan model atau struktur data yang berbeda untuk kode status yang berbeda.

@app.get("/items/{item_id}", responses={
    200: {"model": Item, "description": "The requested item"},
    404: {"description": "Item not found"},
    400: {"description": "Invalid request", "content": {"application/json": {"example": {"detail": "Invalid item ID"}}}},
})
async def read_item(item_id: str):
    # implementation omitted
    pass

Dalam contoh ini, parameter responses digunakan untuk mendokumentasikan kemungkinan respons dengan kode status 200, 404, dan 400. Untuk kode status 400, contoh respons juga disertakan.

Mendokumentasikan Parameter Query dan Body Permintaan

Dalam FastAPI, parameter query dan body permintaan biasanya didefinisikan menggunakan hint tipe Python bersama dengan model Pydantic. Ini memberikan cara yang jelas dan ringkas untuk menentukan data apa yang diharapkan dalam sebuah permintaan. Namun, untuk membuat dokumentasi API yang komprehensif, Anda mungkin perlu menambahkan informasi tambahan seperti deskripsi, contoh, dan batasan validasi. FastAPI memudahkan hal ini dengan menyediakan kelas Query dan Body untuk parameter query dan body permintaan.

Mendokumentasikan Parameter Query

Untuk menambahkan dokumentasi untuk parameter query, Anda dapat menggunakan kelas Query dari FastAPI. Kelas ini menyediakan cara untuk mendefinisikan parameter query dengan metadata tambahan.

from fastapi import FastAPI, Query

app = FastAPI()

@app.get("/items/")
async def read_items(q: Optional[str] = Query(None, description="The query string to filter items", example="item_name")):
    return {"q": q}

Dalam contoh ini, kelas Query digunakan untuk menambahkan deskripsi dan contoh untuk parameter query q. Ketika melihat dokumentasi dalam Swagger UI atau ReDoc, informasi tambahan akan ditampilkan bersama dengan parameter tersebut.

Mendokumentasikan Body Permintaan

Untuk menambahkan dokumentasi untuk body permintaan, Anda dapat menggunakan kelas Body dari FastAPI. Kelas ini memungkinkan Anda mendefinisikan body permintaan dengan metadata tambahan.

from fastapi import FastAPI, Body
from pydantic import BaseModel
from typing import Optional

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

app = FastAPI()

@app.post("/items/")
async def create_item(item: Item = Body(..., description="The item to create", example={"name": "item_name", "price": 42.0})):
    return {"item": item}

Dalam contoh ini, kelas Body digunakan untuk menambahkan deskripsi dan contoh untuk body permintaan item. Informasi tambahan ini akan ditampilkan dalam dokumentasi API bersama dengan body permintaan.

Mendokumentasikan Field dalam Model Pydantic

Anda juga dapat memberikan dokumentasi untuk field-field individual dalam model Pydantic menggunakan kelas Field dari Pydantic.

from pydantic import BaseModel, Field
from typing import Optional

class Item(BaseModel):
    name: str = Field(..., description="The name of the item", example="item_name")
    description: Optional[str] = Field(None, description="A brief description of the item", example="A sample item")
    price: float = Field(..., description="The price of the item", example=42.0)
    tax: Optional[float] = Field(None, description="The tax on the item", example=3.5)

Dalam contoh ini, kelas Field digunakan untuk menambahkan deskripsi dan contoh untuk setiap field dalam model Item. Informasi ini akan ditampilkan dalam dokumentasi API ketika model tersebut digunakan sebagai input atau output.