docsHandler

`docsHandler`

Returns a Shelf Handler that serves the spec and two documentation UIs.

Handler docsHandler(
  OpenApiSpec spec, {
  String? specPath,
  String title = 'API Docs',
  String? swaggerTitle,
  String? redocTitle,
  bool enabled = true,
});

When to use: to give people browsing docs and to give client generators a URL for the spec. Mount it with router.mount(...). To publish the spec somewhere else (a static site, a CI artifact), serialise it with spec.toJson() instead.

Parameter	Type	Default	Description
`spec`	`OpenApiSpec`	required	Serialised on every request to `openapi.json`, so operations added after mounting are included.
`specPath`	`String?`	`null` (the mounted `openapi.json`)	Spec URL the UIs load. An absolute path or a URL with a scheme is used as is; a relative value is resolved against the mount point.
`title`	`String`	`'API Docs'`	HTML `<title>` and header text of both UIs. HTML-escaped.
`swaggerTitle`	`String?`	`title`	Overrides the title for Swagger UI.
`redocTitle`	`String?`	`title`	Overrides the title for Redoc.
`enabled`	`bool`	`true`	When `false`, every route answers `404 Not Found`.

Routes, relative to where the handler is mounted:

Route	Response
`GET openapi.json`	The document, `application/json; charset=utf-8`, `cache-control: no-cache`.
`GET docs`	Swagger UI page, with a link to Redoc.
`GET docs/`	`301` to `docs`.
`GET redoc`	Redoc page, with a link to Swagger UI.
`GET redoc/`	`301` to `redoc`.

Links between the pages and to the spec are built from the mount point (Request.handlerPath), so the handler works at / and under any prefix.

The pages load Swagger UI 5.33.1 and Redoc 2.5.4 from unpkg.com at those exact versions with Subresource Integrity hashes, so the browser refuses a changed file. The viewer needs access to unpkg; the server does not. Swagger UI is configured with persistAuthorization, tryItOutEnabled and filter turned on.

Example

import 'dart:io';

import 'package:gisila_doc/gisila_doc.dart';

final isProd = Platform.environment['APP_ENV'] == 'production';

app.registerController(attacher: (app, router, {String prefix = ''}) {
  UsersController().attachToApp(app, router, spec, prefix: prefix);
  // /reference/openapi.json, /reference/docs, /reference/redoc
  router.mount(
    '/reference/',
    docsHandler(spec, title: 'Acme API', enabled: !isProd),
  );
});

See also: Serve the docs UI.