diff --git a/docs/openapi.yaml b/docs/openapi.yaml deleted file mode 100644 index 564c32bb..00000000 --- a/docs/openapi.yaml +++ /dev/null @@ -1,744 +0,0 @@ -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 - '503': - $ref: '#/components/responses/Timeout' - - /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 - '503': - $ref: '#/components/responses/Timeout' - - /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 - '503': - $ref: '#/components/responses/Timeout' - - /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 - '503': - $ref: '#/components/responses/Timeout' - - /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 - '503': - $ref: '#/components/responses/Timeout' - - /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 - '503': - $ref: '#/components/responses/Timeout' - -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 - Timeout: - description: Service Unavailable