<rapi-pdf> API Reference
A spec URL field and a button that turns an OpenAPI spec into a PDF, in the browser. The rapipdf package also makes the same PDF in Node.
Config Options
HTML Attributes#
Set on the <rapi-pdf> element in HTML, or changed at runtime with setAttribute.
Spec Attributes#1
| Attribute Name | Description & Allowed Values | Default |
|---|---|---|
URL of the spec: OpenAPI 3.x or Swagger 2.0, JSON or YAML. It fills the input field, and the reader can change it there. generatePdf(spec) takes a spec object or text instead. | — |
Output Attributes#2
| Attribute Name | Description & Allowed Values | Default |
|---|---|---|
Allowed: open shows the PDF in a new tab; download saves it. If the browser blocks the new tab, the PDF is downloaded instead. | open | |
Name of the downloaded file; .pdf is added when it is missing. | api-reference |
PDF Content Attributes#9
| Attribute Name | Description & Allowed Values | Default |
|---|---|---|
Title on the cover page. | API Reference | |
Text at the bottom of every page. | — | |
Allowed: false leaves out the cover page with the API's title, version, description and contact. | true | |
Allowed: false leaves out the table of contents. | true | |
Allowed: false leaves out the security schemes. | true | |
Allowed: false leaves out the operations: their parameters, request bodies and responses. | true | |
Allowed: true adds the request and response examples. | false | |
Allowed: true adds a closing list of every operation. | false | |
Allowed: false keeps the tags in the spec's order instead of sorting them by name. | true |
PDF Look Attributes#3
| Attribute Name | Description & Allowed Values | Default |
|---|---|---|
Allowed: How schemas are drawn: as an indented object, or as a table. | object | |
Color of headings and operation titles. | #b44646 | |
Color of section labels and table headers. | #005b96 |
Element Look Attributes#6
| Attribute Name | Description & Allowed Values | Default |
|---|---|---|
Text of the button. | GENERATE PDF | |
Background color of the button (and the input's border). | — | |
Text color of the button. | — | |
Background color of the spec URL field. | — | |
Text color of the spec URL field. | — | |
Allowed: true hides the spec URL field, leaving only the button. | false |
JavaScript API
DOM Methods#
Called on the <rapi-pdf> element, for example document.querySelector('rapi-pdf').
Programmatic Control Example
const pdf = document.querySelector('rapi-pdf');
await pdf.generatePdf(); // open or download, as the output attribute says
await pdf.generatePdf(specObject); // a spec object or spec text instead of spec-url
const blob = await pdf.getPdfBlob(); // the PDF itself, nothing opened or downloaded| Method Name | Description & Usage |
|---|---|
Makes the PDF and opens it in a new tab, or downloads it when output="download". Takes a
spec URL, spec text or a spec object; without one, the spec-url attribute. Resolves when
the PDF is open or the download has started. | |
Makes the PDF and resolves with it as a Blob, without opening or downloading anything: for
a page that shows or uploads the PDF itself, or where new tabs are not allowed. |
Runtime Hooks
Lifecycle & Console Events#
CustomEvents dispatched by <rapi-pdf>. Listen to them with addEventListener; the payload is in e.detail.
Event Interceptor Example
const pdf = document.querySelector('rapi-pdf');
pdf.addEventListener('pdf-generated', (e) => console.log('Made a PDF:', e.detail.output));
pdf.addEventListener('pdf-error', (e) => console.error(e.detail.error));| Event Name | Description & Payload |
|---|---|
A PDF was made. e.detail.output is
"open", "download" or "blob". | |
The PDF could not be made. e.detail.error is the Error. |