مستندات API — Swagger

فینچ یک generator مستندات OpenAPI/Swagger داخلی دارد. Endpoint ها را مستقیماً در کدهای Dart با annotation مشخص کنید.

راه‌اندازی

۱. یک ApiController بسازید

import 'package:finch/finch_route.dart';

class UserApiController extends ApiController {
  @override
  String get apiTitle => 'API کاربران';

  @override
  String get apiVersion => '1.0.0';

  @ApiDoc(
    summary: 'دریافت تمام کاربران',
    description: 'لیست تمام کاربران فعال را برمی‌گرداند',
    parameters: [
      ApiParameter(name: 'page',  in_: 'query', type: 'integer'),
      ApiParameter(name: 'limit', in_: 'query', type: 'integer'),
    ],
    responses: [
      ApiResponse(statusCode: 200, description: 'موفق'),
      ApiResponse(statusCode: 401, description: 'احراز هویت نشده'),
    ],
  )
  Future<String> getUsers() async {
    // ...
    return rq.renderData(data: users);
  }
}

۲. Route ها را ثبت کنید

router.get('/api/users', UserApiController().getUsers);

۳. ApiDoc را متصل کنید

FinchConfigs(
  enableApiDoc: true,
  apiDocPath: '/api/docs',
)

UI مستندات در /api/docs در دسترس است.

ApiParameter

ApiResponse

ApiResponse(
  statusCode: 201,
  description: 'کاربر ایجاد شد',
  schema: {'type': 'object', 'properties': {'id': {'type': 'integer'}}},
)

میانبرهای از پیش‌تعریف‌شده

فینچ annotation های کوتاه‌شده‌ای دارد:

@ApiGet(summary: 'دریافت آیتم')
@ApiPost(summary: 'ایجاد آیتم')
@ApiPut(summary: 'بروزرسانی آیتم')
@ApiDelete(summary: 'حذف آیتم')