مستندسازی API 📖

چرا مستندات مهمه؟

یه API بدون مستندات، مثل یه ماشین بدون دفترچه راهنماست! هیچکس نمی‌دونه چطوری ازش استفاده کنه. مستندات خوب به بقیه برنامه‌نویس‌ها (و حتی خود آینده‌تون!) میگه که هر Endpoint چی کار می‌کنه، چه ورودی‌هایی می‌گیره و چه خروجی‌ای می‌ده.

OpenAPI و Swagger: استاندارد صنعتی

OpenAPI Specification (که قبلاً بهش Swagger می‌گفتن) یه استاندارده برای توصیف کردن REST APIها. ما با فرمت YAML یا JSON، تمام جزئیات API رو توصیف می‌کنیم.

Swagger UI یه ابزار خفنه که اون فایل توصیفی رو می‌گیره و یه صفحه وب تعاملی و خوشگل ازش می‌سازه که کاربرا می‌تونن مستقیم تو همون صفحه، API رو تست کنن! (یادتونه FastAPI این کار رو خودکار انجام می‌داد؟)

openapi: 3.0.0
info:
  title: API کاربران ساده
  version: 1.0.0
paths:
  /users:
    get:
      summary: لیست همه کاربران را برمی‌گرداند
      responses:
        '200':
          description: یک لیست از کاربران
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: integer
                    name:
                      type: string