API-documentatie en Swagger Gids

Welkom bij de Finch API-documentatie en Swagger gids! Deze handleiding beschrijft hoe je API-documentatie voor je Finch-applicatie maakt en hoe je Swagger kunt integreren voor interactieve documentatie.

Definiëren van API-documentatie

API-documentatie omvat drie hoofdonderdelen:

• Swagger toevoegen aan routes
• Een ApiDoc route toevoegen
• ApiDoc voor elke route definiëren

Finch biedt de ApiDoc-klasse om API-eindpunten te documenteren. Hiermee definieer je parameters, request body en response-structuur. Voorbeeld:

Api documentatie controller

final apiController = ApiController(
   title: "API Documentation",
   app: app,
);

// Routes die je aan FinchApp routing toevoegt
// OpenApi json output
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 voor elke route definiëren

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: "Update one person by id.",
        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: "Get one person by id.",
        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: "Delete one person by id.",
        parameters: [
          ApiParameter<String>('id', isRequired: true, paramIn: ParamIn.path),
        ],
      ),
    );
  }
}

/// ApiDoc toevoegen aan routes (voorbeeld)
FinchRoute(
  key: 'root.person.show',
  path: 'api/person/{id}',
  extraPath: ['example/person/{id}'],
  index: homeController.onePerson,
  methods: Methods.GET_POST,
  apiDoc: ApiDocuments.onePerson,
),