dart_frog_open_api 0.1.5

OpenAPI/Swagger spec generator for Dart Frog — file-system based route scanning.

example/example.dart

// A condensed, single-file overview of `dart_frog_open_api`.
//
// In a real Dart Frog app these pieces live in separate files (Dart Frog uses
// file-system routing): each ApiDoc sits next to its route under `routes/`, the
// config under `open_api/`, and the wiring in `main.dart`. They're gathered here
// so you can see the whole flow at a glance.
//
// The request/response schemas (`$CreateUserDtoSchema`, `$UserDtoSchema`) are
// generated by `zto` + build_runner from your annotated DTOs — see
// https://pub.dev/packages/zto. Run `dart run build_runner build` to produce them.

import 'dart:async';
import 'dart:io';

import 'package:dart_frog/dart_frog.dart';
import 'package:dart_frog_open_api/dart_frog_open_api.dart';
import 'package:zto/zto.dart';

// Normally these come from build_runner as `$CreateUserDtoSchema` / `$UserDtoSchema`.
// They're declared inline here only so this overview compiles on its own.
const $CreateUserDtoSchema = ZtoSchema(typeName: 'CreateUserDto', descriptors: []);
const $UserDtoSchema = ZtoSchema(typeName: 'UserDto', descriptors: []);

// ── 1. Document routes (normally each lives next to its handler in routes/) ──

/// OpenAPI for `POST /users` and `GET /users`.
final usersApiDoc = Api.path()
    .get(
      (op) => op
          .summary('List users')
          .tag('Users')
          .queryParam('search', description: 'Filter by name')
          .response(200, listOfZtoSchema: $UserDtoSchema, description: 'Users'),
    )
    .post(
      (op) => op
          .summary('Create a user')
          .tag('Users')
          .body($CreateUserDtoSchema)
          .response(201, ztoSchema: $UserDtoSchema, description: 'Created')
          .response(422, description: 'Validation failed'),
    )
    .build();

/// OpenAPI for `GET /users/{id}` and `DELETE /users/{id}`.
final userByIdApiDoc = Api.path()
    .param('id', ParamType.string, description: 'User id')
    .get((op) => op.summary('Get a user').tag('Users').ok(ztoSchema: $UserDtoSchema).notFound())
    .delete((op) => op.summary('Delete a user').tag('Users').noContent())
    .build();

// ── 2. Map each OpenAPI path string → its ApiDoc (open_api/paths.dart) ──

final apiPathSchemas = <String, PathSchema>{
  '/users': usersApiDoc,
  '/users/{id}': userByIdApiDoc,
};

// ── 3. Build the config (open_api/config.dart) ──

final bearer = OpenApiSecurity.bearer();

final openApiConfig = OpenApiConfig(
  info: const OpenApiInfo(
    title: 'My API',
    description: 'Example API documented with dart_frog_open_api.',
    servers: ['http://localhost:8080'],
  ),
  pathSchemas: apiPathSchemas,
  specUrl: '/swagger/json',
  declaredSecuritySchemes: [bearer],
  globalSecurity: [bearer.componentKey], // applied to every operation
  // Docs are closed (404) by default — enable them per environment:
  security: const SecurityConfig(enabled: true),
);

// ── 4. Initialize once at startup (main.dart → init) ──

late final DartFrogOpenApi openApi;

Future<void> init(InternetAddress ip, int port) async {
  openApi = DartFrogOpenApi(config: openApiConfig);
}

// ── 5. Expose the UI + spec (each is a Dart Frog route file) ──

/// routes/swagger/index.dart → Swagger UI page.
FutureOr<Response> swaggerUi(RequestContext context) =>
    openApi.swaggerUiHandler()(context);

/// routes/swagger/json.dart → the OpenAPI 3.0 JSON spec (served at `specUrl`).
FutureOr<Response> swaggerJson(RequestContext context) =>
    openApi.openApiJsonHandler()(context);

/// routes/scalar/index.dart → Scalar UI page (alternative to Swagger UI).
FutureOr<Response> scalarUi(RequestContext context) =>
    openApi.scalarUiHandler()(context);