Dokumentasi yang ditulis terpisah dari kode hampir pasti kadaluarsa: endpoint baru ditambahkan, parameter lupa dicatat, dan klien menemukan selisihnya dengan cara yang paling menyakitkan — lewat error di produksi. OpenAPI menyelesaikannya dengan membalik arah: dari kode yang sudah tervalidasi type hints, FastAPI membangkitkan spesifikasi lengkap dalam format yang bisa dibaca mesin maupun manusia. Dokumentasi tidak lagi menjadi dokumen terpisah yang harus dijaga — documentation adalah byproduct dari kode yang benar. Chapter ini membaca isi spesifikasi itu, lalu memanfaatkannya untuk menghasilkan dokumentasi yang layak tampil tanpa satu berkas HTML pun.

Apa itu OpenAPI #

OpenAPI adalah spesifikasi (saat ini versi 3.x) yang mendeskripsikan seluruh permukaan sebuah REST API: daftar path, method, parameter, request body, response, dan skema data — ditulis dalam JSON atau YAML. Karena formatnya baku, ekosistem tool bisa dibangun di atasnya: generator klien untuk berbagai bahasa, mock server, hingga halaman dokumentasi interaktif seperti Swagger UI dan ReDoc. FastAPI membaca decorator, type hints, dan model Pydantic, lalu menerbitkan spesifikasi ini otomatis di path /openapi.json — tidak ada yang perlu kita tulis dua kali.

Membaca openapi.json #

Kode berikut membangun API kecil yang kaya metadata, lalu membedah isi spesifikannya (dijalankan lewat TestClient, tanpa server):

python 
from fastapi import FastAPI
from fastapi.testclient import TestClient
from pydantic import BaseModel, Field


class TugasBaru(BaseModel):
    judul: str = Field(min_length=3, examples=["Belajar FastAPI"])


app = FastAPI(
    title="API Manajemen Tugas",
    version="1.0.0",
    description="API sederhana untuk mengelola daftar tugas harian.",
)


@app.post("/tugas", tags=["tugas"], status_code=201, summary="Buat tugas baru")
def buat_tugas(tugas: TugasBaru):
    """
    Membuat satu tugas baru pada koleksi tugas.

    - **judul**: nama tugas, 3-100 karakter
    """
    return {"id": 1, **tugas.model_dump()}


@app.get("/tugas", tags=["tugas"])
def daftar_tugas():
    """Mengembalikan seluruh tugas yang tersimpan."""
    return []


client = TestClient(app)

r = client.get("/openapi.json")
skema = r.json()
print(r.status_code, sorted(skema["paths"]))
print(skema["info"])

post = skema["paths"]["/tugas"]["post"]
print(post["summary"], post["tags"])
print(post["description"])
print(skema["components"]["schemas"]["TugasBaru"])

r = client.get("/docs")
print("/docs:", r.status_code, r.headers["content-type"])
r = client.get("/redoc")
print("/redoc:", r.status_code, r.headers["content-type"])

Output yang Dihasilkan:

text 
200 ['/tugas']
{'title': 'API Manajemen Tugas', 'description': 'API sederhana untuk mengelola daftar tugas harian.', 'version': '1.0.0'}
Buat tugas baru ['tugas']
Membuat satu tugas baru pada koleksi tugas.

- **judul**: nama tugas, 3-100 karakter
{'properties': {'judul': {'type': 'string', 'minLength': 3, 'title': 'Judul', 'examples': ['Belajar FastAPI']}}, 'type': 'object', 'required': ['judul'], 'title': 'TugasBaru'}
/docs: 200 text/html; charset=utf-8
/redoc: 200 text/html; charset=utf-8

Mari kita telaah asal setiap potongannya:

  1. Baris 10-14 (app = FastAPI(title=..., version=..., description=...)): metadata aplikasi menjadi bagian info pada spesifikasi — terlihat pada baris kedua output.
  2. Baris 17 (tags=["tugas"], summary="Buat tugas baru"): summary menjadi judul operasi; tags mengelompokkan endpoint sehingga dokumentasi bisa menyusun bagian per kelompok.
  3. Baris 19-23 ("""..."""): docstring fungsi menjadi description operasi — teks pada baris keempat sampai keenam output persis isi docstring, dan FastAPI merendernya sebagai Markdown, ditandai sintaks **judul**.
  4. Baris 7 (Field(min_length=3, examples=[...])): constraint validasi dari Chapter Request Models dan Validation mengalir ke skema JSON — minLength: 3 dan contoh nilai Belajar FastAPI tampil pada bagian components.schemas. Inilah bukti dokumen dan aturan validasi lahir dari satu sumber.
  5. Baris 27 (tags=["tugas"]): kedua endpoint membawa tag sama, jadi di /docs keduanya tampil dalam satu kelompok “tugas”.

Swagger UI dan ReDoc #

Dua baris terakhir output membuktikan bahwa /docs dan /redoc bukan sekadar janji — keduanya merespons 200 dengan text/html. Swagger UI (/docs) adalah halaman interaktif: setiap endpoint bisa dicoba langsung lewat tombol Try it out, lengkap dengan form yang dibangun dari skema. ReDoc (/redoc) menampilkan dokumentasi yang sama dalam tata letak tiga kolom yang nyaman untuk dibaca berurutan. Keduanya tidak perlu dikonfigurasi apa pun.

Satu sisa sebelum API ini pantas disebut matang: memastikan seluruh perilaku di atas tidak rusak oleh perubahan di masa depan — tugas untuk chapter API Testing.