Skip to main content

OpenAPI / Swagger

PDF Server generates a Swagger 2.0 specification describing the render, schema, and examples endpoints for the templates that are actually loaded — so the spec reflects your specific deployment.

Live spec​

curl http://localhost:9999/spec/swagger.json

The server also serves interactive viewers from its static assets (Swagger UI, Redoc, and Scalar), pointed at the live spec. Open the server root and navigate to them.

What the spec contains​

For each loaded template the spec includes:

  • POST /templates/<name>/render — with the template's JSON Schema as the body parameter when a schema.json is present;
  • GET /templates/<name>/schema.json — when a schema exists;
  • GET /templates/<name>/examples-data and one GET /templates/<name>/examples/<example> per example — when examples exist;
  • POST /templates/<name>/preview/render-plan — for composite templates;
  • the /_status route;
  • POST /_debug/templates/<name>/render and GET /_debug/templates/<name>/examples/<example> (both return application/x-tar containing the requested artifacts followed by manifest.json, named by a Content-Disposition header so downloaded bundles do not collide, no server state; a template name that cannot be used as a bundle path is a 400. The archive is streamed as it is produced and never assembled in memory, so manifest.json — which describes every artifact — is necessarily the last entry, and its presence is what tells a complete bundle from an abandoned one. A render that fails is still a bundle and still a 200: it carries the problems that say why, and its manifest lists the artifacts the browser would have produced as unavailable with the render error as their reason), GET and POST /_debug/templates/<name>/html (GET for a data-less preview, POST with the render data as the JSON request body — never a query parameter, so render data never lands in a trace span or a proxy log), and GET /_debug/templates/<name>/assets/<path> (one file from the template's assets/ directory, so a consumer previewing that HTML can resolve the links it carries; served with X-Content-Type-Options: nosniff, Content-Security-Policy: sandbox and Access-Control-Allow-Origin: *, which is what lets an isolated, opaque-origin preview frame load a font) — listed in /spec/swagger.json and mounted only when the server is started with --debug-enabled; absent from both the spec and the router otherwise; see Template structure.

On this documentation site​

The site build can dump the spec from a server running against the example templates and render it here with a viewer. Because the spec is deployment-specific, the version shown corresponds to the example template set. See Build & CI for the generation step.

Swagger 2.0 is accepted by Scalar, Swagger UI, and Redoc directly. If a tool requires OpenAPI 3, convert with swagger2openapi in your pipeline.