FastAPI สร้างเอกสารอัตโนมัติได้อย่างไร?

Question

Accepted Answer

FastAPI **สร้างเอกสาร API แบบโต้ตอบได้โดยอัตโนมัติ** จากโค้ดของคุณ — routes, พารามิเตอร์ และ Pydantic models จะถูกแปลงเป็น OpenAPI schema ซึ่งขับเคลื่อน doc UI ที่เปิดดูได้สองแบบ (Swagger UI และ ReDoc) โดยไม่ต้องทำอะไรเพิ่ม

## คุณได้เอกสารมาฟรี ๆ

```python
class Item(BaseModel):
    name: str
    price: float = Field(gt=0, description="Price in USD")

@app.post("/items", tags=["items"], summary="Create an item")
def create_item(item: Item):
    """Create a new item with a name and price."""   # docstring → endpoint description
    return item
```

เพียงแค่เขียน endpoints และ models ที่มีการระบุชนิด (typed) FastAPI ก็จะสร้างเอกสารที่สมบูรณ์ให้ — โดยไม่ต้องเขียนหรือดูแลไฟล์เอกสารแยกต่างหาก

## doc UI สองตัวที่มีมาให้ในตัว

```text
/docs   → Swagger UI — interactive: browse endpoints AND test them in the browser
          (fill in parameters, send requests, see responses live)
/redoc  → ReDoc — a clean, readable reference-style view
/openapi.json → the raw OpenAPI schema (usable to generate client SDKs, etc.)
```

เข้าไปที่ `/docs` แล้วคุณจะสำรวจทุก endpoint ดูพารามิเตอร์ที่จำเป็นและรูปแบบของ response รวมถึง **ส่ง request จริง** ได้โดยตรงจากเบราว์เซอร์ — มีประโยชน์อย่างยิ่งระหว่างการพัฒนาและสำหรับผู้ใช้งาน API

## เนื้อหาของเอกสารมาจากไหน

```text
Route decorators → paths, HTTP methods, tags, summaries
Type hints       → parameter types, required/optional
Pydantic models  → request/response schemas, field constraints & descriptions
Docstrings       → endpoint descriptions
Field(..., description=, example=) → field-level docs and examples
```

ทุกอย่างได้มาจากโค้ดที่คุณเขียนอยู่แล้ว — เอกสารจึง **ตรงกัน (in sync)** กับการ implement โดยอัตโนมัติ

## การเสริมเนื้อหาให้เอกสาร

```python
app = FastAPI(title="My API", version="1.0", description="...")
@app.get("/x", response_model=Item, responses={404: {"description": "Not found"}})
```

## ทำไมจึงสำคัญ

เอกสารแบบโต้ตอบที่สร้างอัตโนมัติเป็นหนึ่งในฟีเจอร์ที่ได้รับการยกย่องมากที่สุดของ FastAPI และเป็นเหตุผลสำคัญที่ทำให้ได้รับความนิยม

เนื่องจากเอกสารถูกสร้างขึ้นโดยตรงจากโค้ดของคุณ (routes, type hints, Pydantic models, docstrings) มันจึง **ตรงกัน (in sync)** กับการ implement จริงเสมอ — กำจัดปัญหาเรื้อรังที่เอกสารล้าสมัยไปจากความเป็นจริง ซึ่งเป็นปัญหาที่รุมเร้าเอกสารที่เขียนด้วยมือ

Swagger UI แบบโต้ตอบ (`/docs`) ช่วยให้นักพัฒนาและผู้ใช้งาน API สำรวจและ **ทดสอบ endpoint แบบสด ๆ ในเบราว์เซอร์** ได้ ซึ่งช่วยปรับปรุงประสบการณ์ของนักพัฒนาอย่างมากและลดความยุ่งยากในการ integrate

OpenAPI schema ที่สร้างขึ้นยังสามารถใช้ขับเคลื่อนการสร้าง client SDK และ contract testing ได้อีกด้วย

การได้เอกสาร API ที่เป็นมืออาชีพ ถูกต้อง และโต้ตอบได้มาแบบฟรี ๆ — เพียงแค่เขียนโค้ดที่ระบุชนิดอย่างดี — เป็นชัยชนะด้านประสิทธิภาพการทำงานและคุณภาพที่สำคัญ ทำให้นี่เป็นความสามารถที่สำคัญและโดดเด่นของ FastAPI