API-documentatie — Swagger

Finch heeft een ingebouwde OpenAPI/Swagger-documentatiegenerator. Annoteer eindpunten direct in Dart-code.

Installatie

1. Maak een ApiController aan

import 'package:finch/finch_route.dart';

class UserApiController extends ApiController {
  @override
  String get apiTitle => 'Gebruikers-API';

  @override
  String get apiVersion => '1.0.0';

  @ApiDoc(
    summary: 'Alle gebruikers ophalen',
    description: 'Geeft een lijst van alle actieve gebruikers',
    parameters: [
      ApiParameter(name: 'page',  in_: 'query', type: 'integer'),
      ApiParameter(name: 'limit', in_: 'query', type: 'integer'),
    ],
    responses: [
      ApiResponse(statusCode: 200, description: 'Geslaagd'),
      ApiResponse(statusCode: 401, description: 'Niet geauthenticeerd'),
    ],
  )
  Future<String> getUsers() async {
    // ...
    return rq.renderData(data: users);
  }
}

2. Routes registreren

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

3. ApiDoc koppelen

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

De documentatie-UI is beschikbaar op /api/docs.

ApiParameter

ApiResponse

ApiResponse(
  statusCode: 201,
  description: 'Gebruiker aangemaakt',
  schema: {'type': 'object', 'properties': {'id': {'type': 'integer'}}},
)

Voorgedefinieerde snelkoppelingen

Finch heeft verkorte annotaties:

@ApiGet(summary: 'Item ophalen')
@ApiPost(summary: 'Item aanmaken')
@ApiPut(summary: 'Item bijwerken')
@ApiDelete(summary: 'Item verwijderen')