Conas a ghineann FastAPI doiciméadúchán uathoibríoch?

Question

Accepted Answer

Gineann FastAPI **doiciméadúchán API idirghníomhach go huathoibríoch** ó do chód — tiontaítear do bhealach, paraiméadair agus samhailí Pydantic ina ghréine OpenAPI, a chothraíonn dhá chomhéadan doiciméadúcháin inbhraite (Swagger UI agus ReDoc) gan aon iarracht bhreise.

## Faigheann tú doiciméadúchán saor in aisce

```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
```

Ar an drochuair go bhfuil endpoints agus samhailí clóscríofa agat, táirgeann FastAPI doiciméadúchán iomlán — gan aon chomhad doiciméadúcháin ar leith le scríobh nó a chothabháil.

## An dá chomhéadan doiciméadúcháin ionsuite

```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.)
```

Tabhair cuairt ar `/docs` agus is féidir leat gach endpoint a fhiosrú, na paraiméadair riachtanacha agus na cruth freagartha a fheiceáil, agus **iarratais fhíor a sheoladh** go díreach ó bhraisteoireacht — báinteach le linn fforbartha agus d'úsáideoirí an API.

## Cá as a thagann ábhar an doiciméadúcháin

```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
```

Tá gach rud i bhfoirm do chóid atá scríofa agat cheana féin — fanann an doiciméadúchán go huathoibríoch **i gcomhsheasamh** leis an bhfhíordhíriú.

## An doiciméadúchán a shaibhriú

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

## Cén fáth go bhfuil sé tábhachtach

Tá doiciméadúchán API idirghníomhach uathoibríoch ar cheann de na gnéithe ba chéilí de FastAPI agus príomhchúis a thairbhí.

Marapd is ó do chód a ghineann an doiciméadúchán go díreach (bealaigh, leideanna cineál, samhailí Pydantic, docstrings), fanann siad i gcónaí **i gcomhsheasamh** leis an fhíordhíriú — a bhaint amach an fhadhb dhomhanda ar an doiciméadúchán ag fás as dáta, a raibh imirt ag an doiciméadúchán scríofa de láimh.

Tugann an comhéadan Swagger UI idirghníomhach (`/docs`) do fhorbróirí agus do úsáideoirí an API a bheith ábalta endpoints a fhiosrú agus **a thástáil beo sa bhrabhsálaí**, ag feabhas go mór ar thaithí an fhorbróra agus ag laghdú frithchuid an chomhlachais.

Is féidir leis an ghréine OpenAPI ginte SDK client a ghiniúint agus tástála conraidh a dhéanamh freisin.

A fháil doiciméadúchán API gairmiúil, cruinn, idirghníomhach go bunúsach saor in aisce — sa drochuair go bhfuil cód clóscríofa go maith agat — is gealadh suntasach é ar phroifíoilacht agus ar cháilíocht, rud a dhéanann sé ina ghnéithe tábhachtach, ar leith de FastAPI.