/** * Swagger documentation UI for declarative `HttpApi` contracts. * * This module mounts a browser-based Swagger UI route on an `HttpRouter`. The * page renders the OpenAPI document derived from the supplied `HttpApi`, so a * running application can expose interactive API documentation without writing a * separate OpenAPI file. * * **Mental model** * * {@link layer} registers one `GET` route, defaulting to `/docs`. When that * route is requested, the module derives the OpenAPI document with * `OpenApi.fromApi`, embeds it into an HTML page, and boots the bundled Swagger * UI script in the browser. API implementation, middleware, and server wiring * stay with the surrounding `HttpApi` and router layers. * * **Common tasks** * * - Use {@link layer} to mount Swagger UI for an `HttpApi` * - Set `path` when the documentation route should be mounted somewhere other * than `/docs` * - Add OpenAPI annotations to the API definition so the generated UI has the * desired titles, descriptions, servers, security schemes, and operation * metadata * * **Gotchas** * * The mounted route serves HTML, not a raw OpenAPI JSON endpoint. Clients, * gateways, and documentation pipelines that need the specification directly * should derive it separately with `OpenApi.fromApi` or expose a JSON route from * the surrounding API server. * * @since 4.0.0 */ import * as Effect from "../../Effect.ts" import type * as Layer from "../../Layer.ts" import * as HttpRouter from "../http/HttpRouter.ts" import * as HttpServerResponse from "../http/HttpServerResponse.ts" import type * as HttpApi from "./HttpApi.ts" import type * as HttpApiGroup from "./HttpApiGroup.ts" import * as Html from "./internal/html.ts" import * as internal from "./internal/httpApiSwagger.ts" import * as OpenApi from "./OpenApi.ts" const makeHandler = (options: { readonly api: HttpApi.HttpApi }) => { const spec = OpenApi.fromApi(options.api) const response = HttpServerResponse.html(` ${Html.escape(spec.info.title)} Documentation
`) return Effect.succeed(response) } /** * Mounts Swagger UI for an `HttpApi` at the configured path, defaulting to * `/docs`, using the OpenAPI specification generated from the API. * * @category layers * @since 4.0.0 */ export const layer = ( api: HttpApi.HttpApi, options?: { readonly path?: `/${string}` | undefined } ): Layer.Layer => HttpRouter.use(Effect.fnUntraced(function*(router) { const handler = makeHandler({ api }) yield* router.add("GET", options?.path ?? "/docs", handler) }))