Dokumentasi API dengan Swagger

Kita akan pakai FastAPI + Swagger UI karena simpel dan cocok buat dokumentasi REST API secara otomatis.

Install Python dan pip

Ubuntu 24.04 biasanya udah include Python 3. Tapi kita pastikan dulu:

sudo apt update
sudo apt install python3 python3-pip -y

Buat Virtual Environment (opsional tapi disarankan)

sudo apt install python3-venv -y
python3 -m venv venv
source venv/bin/activate

Install FastAPI dan Uvicorn

pip install fastapi uvicorn

Buat File Project: `main.py`

# main.py

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI(title="Swagger API - Metro TV", version="1.0")

# Contoh Model
class Item(BaseModel):
    name: str
    price: float
    is_offer: bool = None 

# Route dasar
@app.get("/")
def read_root():
    return {"message": "Hello, Metro TV"}

# Route dengan parameter
@app.get("/items/{item_id}")
def read_item(item_id: int, q: str = None):
    return {"item_id": item_id, "q": q}

# POST endpoint
@app.post("/items/")
def create_item(item: Item):
    return {"item": item}

Jalankan API

uvicorn main:app --reload

Akses Swagger UI

Setelah dijalankan, buka browser dan kunjungi:

http://127.0.0.1:8000/docs

Swagger UI akan otomatis tampil dan mendokumentasikan semua endpoint.

Akses Redoc (Alternatif UI)

http://127.0.0.1:8000/redoc

Export Dokumentasi ke JSON atau YAML

Kalau kamu butuh file dokumentasi:

JSON:

http://127.0.0.1:8000/openapi.json

YAML (butuh converter, contoh pakai `json2yaml`):

pip install json2yaml
curl http://127.0.0.1:8000/openapi.json | json2yaml > openapi.yaml

Catatan:

Kita dapat integrasi Swagger manual (misalnya pakai Flask atau Express.js).
Saat ini, FastAPI sudah auto generate Swagger tanpa ribet coding dokumentasi manual.

Pranala Menarik

Web Programming