Swagger UI Docs

What is an app without docs? Flint Dart ships with auto-generated Swagger UI so your team and API users can explore endpoints instantly. Enable docs and visit http://localhost:3000/docs.

void main() {
  final app = Flint(
    enableSwaggerDocs: true,
  );

  app.listen(port: 3000);
}

Swagger docs are auto-generated during development when you restart the server, so you stay productive. The JSON is written to docs/swagger.json and Swagger UI reads it automatically at runtime.

Route Annotations

Use doc comments above routes to describe your API.

/// @summary Create a new user
/// @auth bearer
/// @response 201 Created
/// @response 400 Bad request
/// @param id path string required User ID
/// @query page integer optional Page number
/// @body {"name": "string", "email": "string"}
app.post('/users', controller.create);

• @summary - short description shown in Swagger UI.

• @auth - auth type (default: bearer).

• @response - status code + description.

• @param - path or query parameters (name location type required).

• @query - query parameter (name type required).

• @body - JSON body schema example.

• @prefix - override prefix for a RouteGroup.

• @server - add server URLs for docs.

HTTP QUERY Docs

Flint recognizes app.query(...) routes during docs generation. OpenAPI 3.0 does not define a standard query operation key, so Flint keeps the document valid by preserving QUERY operations as vendor extensions instead of mapping them incorrectly to GET or POST.

Generated QUERY operations include x-http-method: QUERY, a path-level x-flint-query entry, and a top-level x-flint-query-routes section.

/// @summary Search products
/// @body {"category": "string", "inStock": true}
app.query('/products/search', (Context ctx) async {
  final filters = await ctx.req.json();
  return ctx.res?.json({'filters': filters});
});

Some OpenAPI viewers may not render these operations as normal method rows. Use the Flint extensions when integrating with tooling that needs QUERY route metadata.

WebSocket Handshake Docs

Flint now includes app.websocket(...) routes in generated docs. They are emitted as Swagger-friendly GET operations with a 101 Switching Protocols response plus Flint-specific metadata such as x-websocket, x-flint-transport, and a top-level x-websockets block.

/// @summary Chat websocket handshake
/// @response 101 Switching Protocols
app.websocket('/ws/chat', (Context ctx) {
  ctx.socket?.join('lobby');
});

This keeps the generated OpenAPI document valid while still making WebSocket routes visible in the docs.