diff --git a/docs/openapi.yaml b/docs/openapi.yaml new file mode 100644 index 00000000..26ba4599 --- /dev/null +++ b/docs/openapi.yaml @@ -0,0 +1,730 @@ +openapi: 3.0.3 +info: + title: Gotenberg + version: 7.x + license: + name: MIT + url: 'https://github.com/gotenberg/gotenberg/blob/main/LICENSE' + contact: + url: 'https://github.com/gotenberg/gotenberg' + description: >- + A Docker-powered stateless API for PDF files. +externalDocs: + url: https://gotenberg.dev +servers: + - url: 'http://localhost:3000' + description: Local server with the default Docker image and port +tags: + - name: chromium + description: Operations of the Chromium module + externalDocs: + url: https://gotenberg.dev/docs/modules/chromium + - name: libreoffice + description: Operations of the Libreoffice module + externalDocs: + url: https://gotenberg.dev/docs/modules/libreoffice + - name: pdfengines + description: Operations of the PDF Engines module + externalDocs: + url: https://gotenberg.dev/docs/modules/pdf-engines +paths: + /forms/chromium/convert/url: + post: + tags: + - chromium + summary: Convert the contents of a given URL to PDF + externalDocs: + url: https://gotenberg.dev/docs/modules/chromium + description: >- + Send a URL in your API request via the `url` form field + Send a remote URL in your API request via the `remoteURL` parameter, and + get the resulting PDF file. The API will fetch the given URL and render + the page to PDF using the underlying headless Chrome instance. + You can optionally include `header.html` and `footer.html` files as part of the request as well. + See externalDocs for more details. + parameters: + - in: header + name: Gotenberg-Output-Filename + description: >- + By default, the API generates a UUID filename. + However, you may also specify the filename per request, + thanks to the Gotenberg-Output-Filename header. + Caution! The API adds the file extension automatically; you don't have to set it. + schema: + type: string + required: false + - in: header + name: Gotenberg-Trace + description: >- + The trace, or request ID, identifies a request in the logs. + + By default, the API generates a UUID trace for each request. + However, you may also specify the trace per request, thanks to the Gotenberg-Trace header. + schema: + type: string + required: false + requestBody: + required: true + description: >- + The request must be `multipart/form-data` that includes a `url` form field. + The API uses a headless Chrome instance to do the conversion, therefore print + parameter such as margins and paper size are also accepted as optional parameters. + content: + multipart/form-data: + schema: + $ref: '#/components/schemas/URLConvertRequestBody' + examples: { } + responses: + '200': + $ref: '#/components/responses/SuccessfulPDF' + '400': + description: Bad Request + + /forms/chromium/convert/html: + post: + tags: + - chromium + summary: Convert a given HTML file to PDF + externalDocs: + url: https://gotenberg.dev/docs/modules/chromium + description: >- + Send an HTML file called `index.html` as a multipart form request, and + get the resulting PDF file. You can optionally include `header.html` and + `footer.html` files as part of the request as well. + See externalDocs for more details. + parameters: + - in: header + name: Gotenberg-Output-Filename + description: >- + By default, the API generates a UUID filename. + However, you may also specify the filename per request, + thanks to the Gotenberg-Output-Filename header. + Caution! The API adds the file extension automatically; you don't have to set it. + schema: + type: string + required: false + - in: header + name: Gotenberg-Trace + description: >- + The trace, or request ID, identifies a request in the logs. + + By default, the API generates a UUID trace for each request. + However, you may also specify the trace per request, thanks to the Gotenberg-Trace header. + schema: + type: string + required: false + requestBody: + content: + multipart/form-data: + schema: + $ref: '#/components/schemas/HTMLConvertRequestBody' + description: >- + The request body must have an `index.html` file in the `files` array, + as well as all the referred resources on the same level as the + `index.html` file. The request can also include `header.html` and + `footer.html`, given the limitations in the API description above. + responses: + '200': + $ref: '#/components/responses/SuccessfulPDF' + '400': + description: Bad Request + + /forms/chromium/convert/markdown: + post: + tags: + - chromium + summary: Convert a Markdown file to PDF + externalDocs: + url: https://gotenberg.dev/docs/modules/chromium + description: >- + Accepts an HTML file called `index.html` plus markdown files as a multipart + form request and embeds the markdown files into the HTML file using the Golang template + function `toHTML`. + The API will convert the markdown to HTML and embed it into your `index.html` file, + then render the resulting page. You can include your own styling and more in your HTML file. + Refer to the HTML conversion page for all the options you can use when converting + Markdown documents as well. You can optionally include `header.html` and + `footer.html` files as part of the request as well. + See externalDocs for more details. + parameters: + - in: header + name: Gotenberg-Output-Filename + description: >- + By default, the API generates a UUID filename. + However, you may also specify the filename per request, + thanks to the Gotenberg-Output-Filename header. + Caution! The API adds the file extension automatically; you don't have to set it. + schema: + type: string + required: false + - in: header + name: Gotenberg-Trace + description: >- + The trace, or request ID, identifies a request in the logs. + + By default, the API generates a UUID trace for each request. + However, you may also specify the trace per request, thanks to the Gotenberg-Trace header. + schema: + type: string + required: false + requestBody: + content: + multipart/form-data: + schema: + $ref: '#/components/schemas/MarkdownConvertRequestBody' + description: >- + The request body must have an `index.html` file in the `files` array, + as well as all the referred markdown resources on the same level as + the `index.html` file. + responses: + '200': + $ref: '#/components/responses/SuccessfulPDF' + '400': + description: Bad Request + + /forms/libreoffice/convert: + post: + tags: + - libreoffice + summary: Convert an Office document to PDF + externalDocs: + url: https://gotenberg.dev/docs/modules/libreoffice + description: >- + This route accepts multipart/form-data requests and files with the following extensions: + + .bib .doc .xml .docx .fodt .html .ltx .txt .odt .ott .pdb .pdf .psw .rtf + .sdw .stw .sxw .uot .vor .wps .epub .png .bmp .emf .eps .fodg .gif .jpg + .met .odd .otg .pbm .pct .pgm .ppm .ras .std .svg .svm .swf .sxd .sxw + .tiff .xhtml .xpm .fodp .potm .pot .pptx .pps .ppt .pwp .sda .sdd .sti + .sxi .uop .wmf .csv .dbf .dif .fods .ods .ots .pxl .sdc .slk .stc .sxc + .uos .xls .xlt .xlsx .tif .jpeg .odp + + By default, if you send more than one file to convert, the route returns a ZIP archive of the + resulting PDF files. However, you may prefer to merge all the PDF files into an individual PDF file. + + > **Attention:** The files will be merged alphabetically for the + resulting PDF. + + You may also specify the page ranges to convert from the incoming Office + documents. The expected format is the same as the one from the print + options of LibreOffice, e.g. `1-1` or `1-4`. + + > **Attention:** if more than one document, the page ranges will be + applied for each document. + + See externalDocs for more details. + parameters: + - in: header + name: Gotenberg-Output-Filename + description: >- + By default, the API generates a UUID filename. + However, you may also specify the filename per request, + thanks to the Gotenberg-Output-Filename header. + Caution! The API adds the file extension automatically; you don't have to set it. + schema: + type: string + required: false + - in: header + name: Gotenberg-Trace + description: >- + The trace, or request ID, identifies a request in the logs. + + By default, the API generates a UUID trace for each request. + However, you may also specify the trace per request, thanks to the Gotenberg-Trace header. + schema: + type: string + required: false + requestBody: + content: + multipart/form-data: + schema: + $ref: '#/components/schemas/OfficeConvertRequestBody' + responses: + '200': + $ref: '#/components/responses/SuccessfulPDF' + '400': + description: Bad Request, e.g. Both 'pdfFormat' and 'nativePdfA1aFormat' form values are provided + + /forms/pdfengines/merge: + post: + tags: + - pdfengines + summary: Merge multiple PDFs into a single PDF + externalDocs: + url: https://gotenberg.dev/docs/modules/pdf-engines + description: >- + You can send multiple PDF files to this endpoint, the API will merge + them into a single PDF and return the resulting PDF file. + + > **Attention:** The PDF files will be merged alphabetically. + parameters: + - in: header + name: Gotenberg-Output-Filename + description: >- + By default, the API generates a UUID filename. + However, you may also specify the filename per request, + thanks to the Gotenberg-Output-Filename header. + Caution! The API adds the file extension automatically; you don't have to set it. + schema: + type: string + required: false + - in: header + name: Gotenberg-Trace + description: >- + The trace, or request ID, identifies a request in the logs. + + By default, the API generates a UUID trace for each request. + However, you may also specify the trace per request, thanks to the Gotenberg-Trace header. + schema: + type: string + required: false + requestBody: + content: + multipart/form-data: + schema: + type: object + properties: + files: + type: array + items: + type: string + format: binary + pdfFormat: + type: string + description: The PDF format of the resulting PDF + example: PDF/A-1a + required: + - files + responses: + '200': + $ref: '#/components/responses/SuccessfulPDF' + '400': + description: Bad Request + + /forms/pdfengines/convert: + post: + tags: + - pdfengines + summary: Convert PDFs into the given formats + externalDocs: + url: https://gotenberg.dev/docs/modules/pdf-engines + description: >- + This route accepts PDF files and a form field pdfFormat for converting them into the specified format. + parameters: + - in: header + name: Gotenberg-Output-Filename + description: >- + By default, the API generates a UUID filename. + However, you may also specify the filename per request, + thanks to the Gotenberg-Output-Filename header. + Caution! The API adds the file extension automatically; you don't have to set it. + schema: + type: string + required: false + - in: header + name: Gotenberg-Trace + description: >- + The trace, or request ID, identifies a request in the logs. + + By default, the API generates a UUID trace for each request. + However, you may also specify the trace per request, thanks to the Gotenberg-Trace header. + schema: + type: string + required: false + requestBody: + content: + multipart/form-data: + schema: + type: object + properties: + files: + type: array + items: + type: string + format: binary + pdfFormat: + type: string + description: The PDF format of the resulting PDF + example: PDF/A-1a + required: + - files + - pdfFormat + responses: + '200': + $ref: '#/components/responses/SuccessfulPDF' + '400': + description: >- + Bad Request, e.g. Invalid form data: no form file found for extensions: [.pdf]; form value 'pdfFormat' is required + +components: + schemas: + HTMLConvertRequestBody: + title: HTML Conversion Request Body + type: object + properties: + files: + type: array + description: >- + List of HTML files to be converted to PDF. An `index.html` file is + required, and any other resources that are referenced through the + HTML file must be included as well. All the referenced files must be + on the same level as the `index.html` file. + items: + type: string + format: binary + marginTop: + type: number + example: 0 + default: 1 + description: Top margin for the page in inches. + marginBottom: + type: number + example: 0 + default: 1 + description: Bottom margin for the page in inches. + marginLeft: + type: number + example: 0 + default: 1 + description: Left margin for the page in inches. + marginRight: + type: number + example: 0 + default: 1 + description: Right margin for the page in inches. + paperWidth: + type: number + example: 8.27 + description: >- + Paper width to be used while rendering the PDF. The default page + size is A4. + paperHeight: + type: number + example: 11.69 + description: >- + Paper height to be used while rendering the PDF. The default page + size is A4. + preferCssPageSize: + type: boolean + description: >- + Define whether to prefer page size as defined by CSS (default false) + default: false + printBackground: + type: boolean + description: >- + Print the background graphics (default false) + default: false + landscape: + type: boolean + example: true + default: false + description: >- + The default orientation for rendering the page is "portrait" mode. + By sending "landscape" parameter, you can ask the output to be + landscape. + scale: + type: number + minimum: 0.1 + maximum: 2.0 + example: 1.5 + description: >- + The scale of the page rendering + default: 1.0 + waitDelay: + type: string + example: 5s + description: >- + When the page relies on JavaScript for rendering, and you don't have access to the page's code, + you may want to wait a certain amount of time to make sure Chromium has fully rendered the page + you're trying to generate. + waitWindowStatus: + type: string + example: done + description: >- + If you have access to the page's code, you may set the window status and tell Gotenberg to wait for a specific value. + For instance + await promises() + window.status = 'ready' + Prefer this option over waitDelay. + extraHttpHeaders: + type: string + description: HTTP headers to send by Chromium while loading the HTML document (JSON format) + nativePageRanges: + type: string + example: 1-4 + description: >- + The page ranges to be converted to PDF for the incoming Office + documents. + pdfFormat: + type: string + description: >- + The PDF format of the resulting PDF. + Caution! You cannot use both nativePdfA1aFormat and pdfFormat form fields. + example: PDF/A-1a + required: + - files + MarkdownConvertRequestBody: + title: Markdown Conversion Request Body + type: object + properties: + files: + type: array + items: + type: string + format: binary + marginTop: + type: number + example: 0 + default: 1 + description: Top margin for the page in inches. + marginBottom: + type: number + example: 0 + default: 1 + description: Bottom margin for the page in inches. + marginLeft: + type: number + example: 0 + default: 1 + description: Left margin for the page in inches. + marginRight: + type: number + example: 0 + default: 1 + description: Right margin for the page in inches. + paperWidth: + type: number + example: 8.27 + description: >- + Paper width to be used while rendering the PDF. The default page + size is A4. + paperHeight: + type: number + example: 11.69 + description: >- + Paper height to be used while rendering the PDF. The default page + size is A4. + preferCssPageSize: + type: boolean + description: >- + Define whether to prefer page size as defined by CSS (default false) + default: false + printBackground: + type: boolean + description: >- + Print the background graphics (default false) + default: false + landscape: + type: boolean + example: true + default: false + description: >- + The default orientation for rendering the page is "portrait" mode. + By sending "landscape" parameter, you can ask the output to be + landscape. + scale: + type: number + minimum: 0.1 + maximum: 2.0 + example: 1.5 + description: >- + The scale of the page rendering + default: 1.0 + waitDelay: + type: string + example: 5s + description: >- + When the page relies on JavaScript for rendering, and you don't have access to the page's code, + you may want to wait a certain amount of time to make sure Chromium has fully rendered the page + you're trying to generate. + waitWindowStatus: + type: string + example: done + description: >- + If you have access to the page's code, you may set the window status and tell Gotenberg to wait for a specific value. + For instance + await promises() + window.status = 'ready' + Prefer this option over waitDelay. + extraHttpHeaders: + type: string + description: HTTP headers to send by Chromium while loading the HTML document (JSON format) + nativePageRanges: + type: string + example: 1-4 + description: >- + The page ranges to be converted to PDF for the incoming Office + documents. + pdfFormat: + type: string + description: >- + The PDF format of the resulting PDF. + Caution! You cannot use both nativePdfA1aFormat and pdfFormat form fields. + example: PDF/A-1a + required: + - files + URLConvertRequestBody: + title: URL Conversion Request Body + type: object + properties: + url: + type: string + example: 'https://google.com' + files: + description: Optional files named header.html and footer.html + type: array + items: + type: string + format: binary + marginTop: + type: number + example: 0 + default: 1 + description: Top margin for the page in inches. + marginBottom: + type: number + example: 0 + default: 1 + description: Bottom margin for the page in inches. + marginLeft: + type: number + example: 0 + default: 1 + description: Left margin for the page in inches. + marginRight: + type: number + example: 0 + default: 1 + description: Right margin for the page in inches. + paperWidth: + type: number + example: 8.27 + description: >- + Paper width to be used while rendering the PDF. The default page + size is A4. + paperHeight: + type: number + example: 11.69 + description: >- + Paper height to be used while rendering the PDF. The default page + size is A4. + preferCssPageSize: + type: boolean + description: >- + Define whether to prefer page size as defined by CSS (default false) + default: false + printBackground: + type: boolean + description: >- + Print the background graphics (default false) + default: false + landscape: + type: boolean + example: true + default: false + description: >- + The default orientation for rendering the page is "portrait" mode. + By sending "landscape" parameter, you can ask the output to be + landscape. + scale: + type: number + minimum: 0.1 + maximum: 2.0 + example: 1.5 + description: >- + The scale of the page rendering + default: 1.0 + waitDelay: + type: string + example: 5s + description: >- + When the page relies on JavaScript for rendering, and you don't have access to the page's code, + you may want to wait a certain amount of time to make sure Chromium has fully rendered the page + you're trying to generate. + waitWindowStatus: + type: string + example: done + description: >- + If you have access to the page's code, you may set the window status and tell Gotenberg to wait for a specific value. + For instance + await promises() + window.status = 'ready' + Prefer this option over waitDelay. + extraHttpHeaders: + type: string + description: HTTP headers to send by Chromium while loading the HTML document (JSON format) + nativePageRanges: + type: string + example: 1-4 + description: >- + The page ranges to be converted to PDF for the incoming Office + documents. + pdfFormat: + type: string + description: >- + The PDF format of the resulting PDF. + Caution! You cannot use both nativePdfA1aFormat and pdfFormat form fields. + example: PDF/A-1a + required: + - url + OfficeConvertRequestBody: + title: Office Conversion Request Body + type: object + properties: + files: + type: array + items: + type: string + format: binary + nativePageRanges: + type: string + example: 1-4 + description: >- + The page ranges to be converted to PDF for the incoming Office + documents. **If there are multiple files sent to the API, this page + range will apply to all of the documents**. Empty means all pages. + nativePdfA1aFormat: + type: boolean + description: >- + Use unoconv to convert the resulting PDF to the 'PDF/A-1a' format. + Caution! You cannot use both nativePdfA1aFormat and pdfFormat form fields. + pdfFormat: + type: string + description: >- + The PDF format of the resulting PDF. + Caution! You cannot use both nativePdfA1aFormat and pdfFormat form fields. + example: PDF/A-1a + landscape: + type: boolean + example: true + default: false + description: >- + The default orientation for rendering the page is "portrait" mode. + By sending "landscape" parameter, you can ask the output to be + landscape. + merge: + type: boolean + description: >- + Merge all PDF files into an individual PDF file. + required: + - files + MergeFilesRequestBody: + title: Merge Files Request Body + type: object + properties: + files: + type: array + items: + type: string + format: binary + required: + - files + securitySchemes: { } + responses: + SuccessfulPDF: + description: Resulting PDF file from the conversion. + content: + application/pdf: + schema: + type: string + format: binary \ No newline at end of file