پرش به محتویات

گام های اولیه

ساده ترین پروژه FastAPI می تواند به شکل زیر باشد: 

from fastapi import FastAPI

app = FastAPI()


@app.get("/")
async def root():
    return {"message": "Hello World"}

لطفاً کد زیر را در یک فایل با نام main.py قرار دهید.

برای اجرا به صورت live server ، کد را اجرا کنید.

$ uvicorn main:app --reload

<span style="color: green;">INFO</span>:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
<span style="color: green;">INFO</span>:     Started reloader process [28720]
<span style="color: green;">INFO</span>:     Started server process [28722]
<span style="color: green;">INFO</span>:     Waiting for application startup.
<span style="color: green;">INFO</span>:     Application startup complete.

نکته

دستور 'uvicorn main:app' به این موارد اشاره دارد:

  • "main": فایل "main.py" ("ماژول" پایتون).
  • "app": شی ایجاد شده در "main.py" با خط "app = FastAPI()".
  • "--reload": سرور را پس از تغییر کد راه اندازی مجدد کنید. فقط برای توسعه استفاده کنید.

در خروجی، یک خط با چیزی مانند زیر خواهید دید:

INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)

این خط نشان می‌دهد که برنامه شما در local machine شما در چه آدرسی قرار گرفته است و از چه URLی برای دسترسی به برنامه استفاده می کنید.

بررسی کنید

مرورگر خود را در آدرس http://127.0.0.1:8000 باز کنید.

شما پاسخ JSON را به شکل زیر مشاهده خواهید کرد:

{"message": "Hello World"}

اسناد API تعاملی (Interactive API docs)

اکنون به http://127.0.0.1:8000/docs بروید.

اسناد API تعاملی خودکار را خواهید دید (ارائه شده توسط Swagger UI):

Swagger UI

اسناد API جایگزین (Alternative API docs)

و اکنون به http://127.0.0.1:8000/redoc بروید .

اسناد خودکار جایگزین را خواهید دید (ارائه شده توسط ReDoc): ReDoc

OpenAPI

FastAPI با استفاده از استاندارد OpenAPI برای تعریف APIها، یک "schema" با تمام API شما ایجاد می کند.

"schema" (طرحواره)

"schema" تعریف یا توصیف چیزی است. نه کدی که آن را پیاده سازی می کند، بلکه فقط یک توضیح انتزاعی است.

"schema" API

در این مورد، OpenAPI مشخصاتی است که نحوه تعریف یک شمای API شما

این تعریف schema شامل مسیرهای API شما، پارامترهای احتمالی آنها و غیره است.

"schema" داده

اصطلاح "schema" ممکن است به شکل برخی از داده‌ها مانند محتوای JSON نیز اشاره داشته باشد.

در آن صورت، این به معنای ویژگی‌های JSON، و انواع داده‌های آنها و غیره است.

OpenAPI و JSON Schema

OpenAPI یک schema API برای API شما تعریف می کند. و این schema شامل تعاریف (یا "schema ها") داده های ارسال و دریافت شده توسط API شما با استفاده از JSON Schema، استاندارد schema های داده JSON است.

«openapi.json» را بررسی کنید

اگر کنجکاو هستید که schema OpenAPI خام چگونه به نظر می رسد، FastAPI به طور خودکار یک JSON (شما) با توضیحات همه API شما تولید می کند.

می‌توانید مستقیماً آن را در: http://127.0.0.1:8000/openapi ببینید .json.

یک JSON را نشان می دهد که با چیزی شبیه به:

{
    "openapi": "3.1.0",
    "info": {
        "title": "FastAPI",
        "version": "0.1.0"
    },
    "paths": {
        "/items/": {
            "get": {
                "responses": {
                    "200": {
                        "description": "Successful Response",
                        "content": {
                            "application/json": {

OpenAPI برای چیست

schema OpenAPI همان چیزی است که دو سیستم اسناد تعاملی را شامل می شود.

و ده ها گزینه جایگزین وجود دارد که همه بر اساس OpenAPI هستند. شما به راحتی می توانید هر یک از آن جایگزین ها را به برنامه خود که با FastAPI ساخته شده است اضافه کنید.

همچنین می توانید از آن برای تولید کد به صورت خودکار برای کلاینت هایی که با API شما ارتباط برقرار می کنند استفاده کنید. به عنوان مثال، برنامه های frontend، تلفن همراه یا IoT.

مرحله ۱: import FastAPI

from fastapi import FastAPI

app = FastAPI()


@app.get("/")
async def root():
    return {"message": "Hello World"}

"FastAPI" یک کلاس پایتون است که تمام عملکردها را برای API شما فراهم می کند.

جزئیات فنی

«FastAPI» کلاسی است که مستقیماً از «Starlette» به ارث می‌برد. می‌توانید با "FastAPI" نیز از همه قابلیت‌های Starlette استفاده کنید.

مرحله۲ : یک 'instance' از "FastAPI" ایجاد کنید

```"Python hl_lines="3" from fastapi import FastAPI

app = FastAPI()

@app.get("/") async def root(): return {"message": "Hello World"}

در اینجا، متغیر 'app' یک "نمونه" (instance) از کلاس 'FastAPI' خواهد بود.

این نمونه اصلی تعامل شما برای ایجاد تمام (API) خواهد بود.

این "app" همان متغیری است که توسط 'uvicorn' در دستور زیر مورد اشاره قرار می‌گیرد:

<div class="termy">

```console
$ uvicorn main:app --reload

<span style="color: green;">INFO</span>:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)

اگر برنامه خود را مانند زیر ایجاد کنید:

from fastapi import FastAPI

my_awesome_api = FastAPI()


@my_awesome_api.get("/")
async def root():
    return {"message": "Hello World"}

و آن را در یک فایل به نام 'main.py' قرار دهید، سپس می‌توانید 'uvicorn' را به صورت زیر فراخوانی کنید:

$ uvicorn main:my_awesome_api --reload

<span style="color: green;">INFO</span>:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)

مرحله ۳: ایجاد یک path operation (عملیات مسیر)

path

"path" در اینجا به آخرین قسمت URL که از '/' اول شروع می‌شود، اشاره دارد.

بنابراین، در یک URL مانند:

https://example.com/items/foo

... مسیر این گونه خواهد بود:

/items/foo

اطلاعات

یک "path" معمولاً "endpoint" یا "route" نیز نامیده می شود.

هنگام ساختن یک API، «مسیر» راه اصلی برای جداسازی «resources» و «concerns» است.

Operation

"Operation" در اینجا به یکی از «روش‌های HTTP» اشاره دارد.

یکی از: * POST * GET * PUT * DELETE

...و موارد خاص تر:

  • OPTIONS
  • HEAD
  • PATCH
  • TRACE

در پروتکل HTTP، شما می‌توانید با استفاده از یک یا چند "روش" (method) از این مسیرها برای برقراری ارتباط استفاده کنید.

هنگام ساختن API، معمولاً از این روش های خاص HTTP برای انجام یک عمل خاص استفاده می کنید.

به طور معمول شما استفاده می کنید:

  • POST: برای ثبت اطلاعات
  • GET: برای خواندن اطلاعات
  • PUT: برای بروزرسانی اطلاعات
  • DELETE: برای پاک کردن اطلاعات

بنابراین، در OpenAPI، به هر یک از متدهای HTTP "operation" گفته می شود.

ما قصد داریم آنها را "operation ها" نیز بنامیم.

یک path operation decorator را تعریف کنید

from fastapi import FastAPI

app = FastAPI()


@app.get("/")
async def root():
    return {"message": "Hello World"}

'@app.get("/")' به FastAPI می‌گوید که تابعی که در زیر آن قرار دارد، مسئول پاسخگویی به درخواست‌هایی است که به این آدرس ارسال می‌شوند:

  • path (مسیر) /
  • با استفاده از یک operation دریافت

اطلاعات @decorator

به آن نحو «@something» در پایتون «دکوراتور» می‌گویند.

شما آن را در بالای یک تابع قرار می دهید. مانند یک کلاه تزئینی زیبا (حدس می‌زنم این اصطلاح از اینجا آمده است).

یک "decorator" تابع زیر را می گیرد و کاری با آن انجام می دهد.

در مورد ما، این دکوراتور به FastAPI می گوید که تابع زیر با path / با operation 'get' مطابقت دارد.

این "path operation decorator" است.

همچنین می توانید از operation های دیگر استفاده کنید:

  • @app.post()
  • @app.put()
  • @app.delete()

و موارد خاص تر:

  • @app.options()
  • @app.head()
  • @app.patch()
  • @app.trace()

نکته

شما آزاد هستید که از هر operation (method HTTP) به دلخواه خود استفاده کنید.

 **FastAPI** هیچ معنای خاصی را اعمال نمی کند.

 اطلاعات در اینجا به عنوان یک دستورالعمل ارائه شده است، نه یک الزام.

 به عنوان مثال، هنگام استفاده از GraphQL، معمولاً تمام اقدامات را فقط با استفاده از operation «POST» انجام می دهید.

مرحله ۴: تعریف path operation function

این "path operation function" ما است:

  • مسیر: «/» است.
  • operation: "POST" است.
  • تابع: تابع زیر "decorator" است (زیر @app.get("/")).

```"Python hl_lines="7" from fastapi import FastAPI

app = FastAPI()

@app.get("/") async def root(): return {"message": "Hello World"}

این یک تابع پایتون است.

هر زمان که درخواستی به URL "`/`" با استفاده از operation "GET" دریافت کند، توسط **FastAPI** فراخوانی می شود.

در این مورد، یک تابع `async` است.

---

همچنین می‌توانید آن را به‌جای «async def» به‌عنوان یک تابع عادی تعریف کنید:

```"Python hl_lines="7"
from fastapi import FastAPI

app = FastAPI()


@app.get("/")
def root():
    return {"message": "Hello World"}

توجه

اگر تفاوت را نمی دانید، Async: "عجله دارید؟" را بررسی کنید.

مرحله ۵: محتوا را برگردانید

from fastapi import FastAPI

app = FastAPI()


@app.get("/")
async def root():
    return {"message": "Hello World"}

می‌توانید مقادیر مانند "list" و "dict" و همچنین مقادیر تکی مثل "str" و "int" را برگردانید.

همچنین می توانید مدل های Pydantic را برگردانید (در ادامه بیشتر در مورد آن خواهید دید).

بسیاری از اشیاء و مدل های دیگر وجود دارند که به طور خودکار به JSON تبدیل می شوند (از جمله ORM ها و غیره). سعی کنید از موارد مورد علاقه خود استفاده کنید، به احتمال زیاد آنها قبلاً از پشتیبانی می شوند.

خلاصه

  • "FastAPI" را وارد کنید.
  • یک نمونه "برنامه" ایجاد کنید.
  • یک path operation decorator بنویسید (مانند @app.get("/")).
  • یک path operation function بنویسید (مانند 'def root(: ...' در بالا).
  • سرور توسعه را اجرا کنید (مانند 'uvicorn main:app --reload').