ترجمه فارسی مستندات فلسک

روش کار ترجمه

برای مشارکت در این ترجمه خوش آمدید!

در اینجا برخی از راهکار های اصلی ترجمه آمده است.

• یک پول ریکوئست ایجاد کنید تا نام خود را به فصلی که میخواهید ترجمه کنید، اضافه کنید.
• این مخزن(apiflask/docs-fa) را فورک کنید و آن را کلون کنید. ({username} را با نام کاربری گیت‌هاب خودتان جایگزین کنید.):

$ git clone https://github.com/{username}/docs-fa
$ cd docs-fa
$ git remote add upstream https://github.com/apiflask/docs-fa

• راهنمای مشارکت را برای ساخت محیط توسعه بخوانید(برای فورک این مرحله را نادیده بگیرید)

• یک برنچ جدید برای ترجمه فایل های داخل docs_fa/ ایجاد کنید.
• دستور mkdocs serve را برای پیشنمایش و بررسی مشکلات احتمالی اجرا کنید.
• یک پول ریکوئست ارسال کنید و منتظر بررسی باشید.

$ pip install -r requirements/docs.txt
$ pip install -e .
$ mkdocs serve

فصل ها

• Home (index.md) @mmdbalkhi
• Documentation Index (docs.md) @mmdbalkhi
• Migrating from Flask (migrating.md) @mmdbalkhi
• Basic Usage (usage.md)
• Request Handling (request.md)
• Response Formatting (response.md)
• Data Schema (schema.md)
• Authentication (authentication.md)
• OpenAPI Generating (openapi.md)
• Swagger UI and Redoc (api-docs.md)
• Configuration (configuration.md)
• Error Handling (error-handling.md)
• Examples (examples.md)
• Comparison and Motivations (comparison.md)
• Authors (authors.md)
• Changelog (changelog.md)
• Contributing Guide (contributing.md)
• API Reference:
  • APIFlask (api/app.md)
  • APIBlueprint (api/blueprint.md)
  • Exceptions (api/exceptions.md)
  • OpenAPI (api/openapi.md)
  • Schemas (api/schemas.md)
  • Fields (api/fields.md)
  • Validators (api/validators.md)
  • Route (api/route.md)
  • Security (api/security.md)
  • Helpers (api/helpers.md)
  • Commands (api/commands.md)

مقدمه

APIFlask یک web-api فریمورک سبک بر اساس فلسک و marshmallow-code است. APIFlask در استفاده ساده، قابل شخصی سازی، استفاده از ORM/ODM-agnostic و ۱۰۰٪ سازگار با اکوسیستم فلسک است.

با APIFlask شما میتوانید:

• دیکریتور های بیشتری برای ویو-فانکشن ها(@app.input(), @app.output(), @app.get(), @app.post() و بیشتر)
• اعتبار سنجی خودکار درخواست ها و سریال زدایی
• سریال سازی و فرمت خودکار پاسخ ها
• ساخت خودکار OpenAPI Specification (OAS, formerly Swagger Specification) تولید مستندات
• ایجاد مستندات تعاملی خودکار برای API
• پشتیبانی از احراز هویت API(با Flask-HTTPAuth)
• پاسخ های خودکار JSON برای ارور های HTTP

پیشنیاز ها

• پایتون 3.7+
• فلسک 1.1.0+

روش نصب

در Linux و macOS:

$ pip3 install apiflask

در ویندوز:

> pip install apiflask

لینک ها

• وبسایت: https://fa.apiflask.com
• مستندات: https://fa.apiflask.com/docs
• ریلیز های PyPI: https://pypi.python.org/pypi/APIFlask
• گزارش تغییرات: https://fa.apiflask.com/changelog
• کد منبع: https://github.com/apiflask/apiflask
• ردیاب مشکلات: https://github.com/apiflask/apiflask/issues
• گفت و گو: https://github.com/apiflask/apiflask/discussions
• توئیتر: https://twitter.com/apiflask

مثال

from apiflask import APIFlask, Schema, abort
from apiflask.fields import Integer, String
from apiflask.validators import Length, OneOf

app = APIFlask(__name__)

pets = [
    {'id': 0, 'name': 'Kitty', 'category': 'cat'},
    {'id': 1, 'name': 'Coco', 'category': 'dog'}
]

class PetIn(Schema):
    name = String(required=True, validate=Length(0, 10))
    category = String(required=True, validate=OneOf(['dog', 'cat']))

class PetOut(Schema):
    id = Integer()
    name = String()
    category = String()

@app.get('/')
def say_hello():
    # برگرداندن یک دیکشنری یا لیست برابر با استفاده از jsonify()
    return {'message': 'Hello!'}

@app.get('/pets/<int:pet_id>')
@app.output(PetOut)
def get_pet(pet_id):
    if pet_id > len(pets) - 1:
        abort(404)
    # همچنین می توانید یک نمونه کلاس مدل ORM/ODM را مستقیماً برگردانید
    # APIFlask آبجکت را به فرمت JSON سریال می کند
    return pets[pet_id]

@app.patch('/pets/<int:pet_id>')
@app.input(PetIn(partial=True))
@app.output(PetOut)
def update_pet(pet_id, data):
    # داده های ورودی تایید شده و تجزیه شده خواهد بود
    # به عنوان دیکشنری به تابع view تزریق شود
    if pet_id > len(pets) - 1:
        abort(404)
    for attr, value in data.items():
        pets[pet_id][attr] = value
    return pets[pet_id]

همچنین میتوانید از ویو های کلاس-بیس با MethodView استفاده کنید

from apiflask import APIFlask, Schema, abort
from apiflask.fields import Integer, String
from apiflask.validators import Length, OneOf
from apiflask.views import MethodView

app = APIFlask(__name__)

pets = [
    {'id': 0, 'name': 'Kitty', 'category': 'cat'},
    {'id': 1, 'name': 'Coco', 'category': 'dog'}
]

class PetIn(Schema):
    name = String(required=True, validate=Length(0, 10))
    category = String(required=True, validate=OneOf(['dog', 'cat']))

class PetOut(Schema):
    id = Integer()
    name = String()
    category = String()

class Hello(MethodView):

    # از نام متود HTTP به عنوان نام متد کلاس استفاده کنید
    def get(self):
        return {'message': 'Hello!'}

class Pet(MethodView):

    @app.output(PetOut)
    def get(self, pet_id):
        """Get a pet"""
        if pet_id > len(pets) - 1:
            abort(404)
        return pets[pet_id]

    @app.input(PetIn(partial=True))
    @app.output(PetOut)
    def patch(self, pet_id, data):
        """Update a pet"""
        if pet_id > len(pets) - 1:
            abort(404)
        for attr, value in data.items():
            pets[pet_id][attr] = value
        return pets[pet_id]

app.add_url_rule('/', view_func=Hello.as_view('hello'))
app.add_url_rule('/pets/<int:pet_id>', view_func=Pet.as_view('pet'))

یا میتوانید از async def با فلسک ۲.۰ استفاده کنید

$ pip install -U flask[async]

import asyncio

from apiflask import APIFlask

app = APIFlask(__name__)

@app.get('/')
async def say_hello():
    await asyncio.sleep(1)
    return {'message': 'Hello!'}

استفاده از async و await برای اطلاعات بیشتر از async def در فلسک ۲.+ ببینید

این را با نام app.py ذخیره کنید و به صورت زیر اجرا کنید.

$ flask run --reload

و حالا میتوانید مستندات API (Swagger UI) را در http://localhost:5000/docs ببینید:

یا میتوانید UI مستندات API را توسط پارامتر docs_ui در هنگام ساخت کلاس APIFlask تغییر دهید.

app = APIFlask(__name__, docs_ui='redoc')

حالا مستندات API توسط Redoc در http://localhost:5000/docs رندر خواهد شد.

مقادیر پشتیبانی شده از docs_ui عبارت اند از:

• swagger-ui (مقدار پیشفرض): Swagger UI
• redoc: Redoc
• elements: Elements
• rapidoc: RapiDoc
• rapipdf: RapiPDF

فایل OpenAPI spec به تولید خودکار در http://localhost:5000/openapi.json در دسترس است. همچنین شما میتوانید spec را با دستور flask spec دریافت کنید.

$ flask spec

برای سایر مثال های کاملتر /examples ببینید.

رابطه با فلسک

APIFlask یک بسته بندی کوچک بروی فلسک است. شما فقط باید تفاوت های زیر را به خاطر بسپارید(برای اطلاعات بیشتر Migrating from Flask را ببینید):

• هنگام ساخت یک برنامه بجای Flask از APIFlask استفاده کنید
• هنگام ساخت بلوپرینت ها بجای Blueprint از APIBlueprint استفاده کنید.
• تابع abort() در APIFlask(apiflask.abort) ارور ها را به صورت JSON بر میگرداند.

برای یک برنامه مینیمال فلسک:

from flask import Flask, request, escape

app = Flask(__name__)

@app.route('/')
def hello():
    name = request.args.get('name', 'Human')
    return f'Hello, {escape(name)}'

و حالا در APIFlask:

from apiflask import APIFlask  # قدم اول
from flask import request, escape

app = APIFlask(__name__)  # قدم دوم

@app.route('/')
def hello():
    name = request.args.get('name', 'Human')
    return f'Hello, {escape(name)}'

در یک کلمه، برای توسعه راحتر web-api، APIFlask، APIFlask و APIBlueprint را فراهم میکند تا آبجکت های Flask و Blueprint را گسترش دهد و همچنین با برخی از ابزار های مفید همراه است. به جز این شما در از فلسک استفاده میکنید.

رابطه با مارشمالو

Apiflask طرحواره مارشمالو را به عنوان طرحواره داده می پذیرد ، از WebARGS برای تأیید داده های درخواست در برابر طرح طرحواره می کند و از APISPEC برای تولید بازنمایی OpenAPI از طرح استفاده می کند. شما می توانید مانند گذشته طرح های مارشمالو را بسازید ، اما Apiflask همچنین برخی از API های مارشمالو را برای راحتی در معرض دید قرار می دهد (این اختیاری است ، شما هنوز هم می توانید همه چیز را مستقیماً از مارشمالو وارد کنید):

• apiflask.Schema: کلاس پایه طرحوارهی مارشمالو
• apiflask.fields: فیلد های ماشرمالو، شامل هر دوی مارشمالو و Flask-Marshmallow می‌شود. مراقب باشید که نام های مستعار (Url, Str, Int, Bool, غیره) حذف شده اند.
• apiflask.validators: اعتبارسنج های مارشمالو

from apiflask import Schema
from apiflask.fields import Integer, String
from apiflask.validators import Length, OneOf
from marshmallow import pre_load, post_dump, ValidationError

اساس

APIFlask یک فورک از APIFairy است و از flask-smorest و FastAPI ( Comparison and Motivations برای مقایسه بین پروژه ها ببینید) الهام گرفته است.