راهنمای مستندسازی API و Swagger

به راهنمای مستندسازی API و Swagger فینچ خوش آمدید! این راهنما شما را با مراحل مستندسازی API برنامه فینچ و یکپارچه‌سازی Swagger برای مستندسازی تعاملی آشنا می‌کند. چه توسعه‌دهنده حرفه‌ای باشید یا تازه‌کار، فینچ مجموعه‌ای قدرتمند از ابزارها را برای ساده‌سازی توسعه وب‌اپلیکیشن سمت سرور ارائه می‌دهد.

تعریف مستندات API

مستندسازی API شامل ۳ بخش اصلی است:

• افزودن Swagger به مسیرها
• افزودن مسیر ApiDoc
• تعریف ApiDoc برای هر مسیر

فینچ راه ساده‌ای برای مستندسازی نقاط پایانی API با استفاده از کلاس ApiDoc فراهم می‌کند. این کلاس به شما اجازه می‌دهد پارامترها، بدنه درخواست و ساختار پاسخ را برای نقاط پایانی API تعریف کنید. مثال:

کنترلر مستندسازی API

final apiController = ApiController(
   title: "مستندات API",
   app: app,
);

// مسیرهایی که باید به روتینگ FinchApp اضافه شوند
// خروجی OpenApi json
FinchRoute(
  key: 'root.api.docs',
  path: 'api/docs',
  index: apiController.indexPublic,
),
// Swagger UI
FinchRoute(
  key: 'root.swagger',
  path: 'swagger',
  index: () => apiController.swagger(rq.url('api/docs')),
),

تعریف ApiDoc برای هر مسیر

class ApiDocuments {
    static Future<ApiDoc> onePerson() async {
    return ApiDoc(
      post: ApiDoc(
        response: {
          '200': [
            ApiResponse<int>('timestamp_start', def: 0),
            ApiResponse<bool>('success', def: true),
            ApiResponse<Map<String, String>>(
              'data',
              def: PersonCollectionFree.formPerson.fields.map((k, v) {
                return MapEntry(k, v.defaultValue?.call());
              }),
            ),
          ],
          '404': r_404,
        },
        description: "به‌روزرسانی یک شخص با شناسه.",
        parameters: [
          ApiParameter<String>(
            'id',
            isRequired: true,
            paramIn: ParamIn.path,
          ),
          ApiParameter<String>(
            'name',
            isRequired: false,
            paramIn: ParamIn.header,
          ),
          ApiParameter<int>(
            'age',
            isRequired: false,
            paramIn: ParamIn.header,
          ),
          ApiParameter<double>(
            'height',
            isRequired: false,
            paramIn: ParamIn.header,
          ),
          ApiParameter<String>(
            'email',
            isRequired: true,
            paramIn: ParamIn.header,
          ),
          ApiParameter<String>(
            'married',
            isRequired: false,
            paramIn: ParamIn.header,
            def: false,
          ),
        ],
      ),
      get: ApiDoc(
        response: {
          '200': [
            ApiResponse<int>('timestamp_start', def: 0),
            ApiResponse<Map<String, String>>(
              'data',
              def: PersonCollectionFree.formPerson.fields.map((k, v) {
                return MapEntry(k, v.defaultValue?.call());
              }),
            ),
          ],
          '404': r_404,
        },
        description: "دریافت یک شخص با شناسه.",
        parameters: [
          ApiParameter<String>('id', isRequired: true, paramIn: ParamIn.path),
        ],
      ),
      delete: ApiDoc(
        response: {
          '200': [
            ApiResponse<int>('timestamp_start', def: 0),
            ApiResponse<bool>('success', def: true),
          ],
          '404': r_404,
        },
        description: "حذف یک شخص با شناسه.",
        parameters: [
          ApiParameter<String>('id', isRequired: true, paramIn: ParamIn.path),
        ],
      ),
    );
  }
}

/// افزودن ApiDoc به مسیرها (مثال)
FinchRoute(
  key: 'root.person.show',
  path: 'api/person/{id}',
  extraPath: ['example/person/{id}'],
  index: homeController.onePerson,
  methods: Methods.GET_POST,
  apiDoc: ApiDocuments.onePerson,
),