mirror of
https://github.com/gotenberg/gotenberg.git
synced 2026-08-08 00:22:14 +01:00
559 lines
18 KiB
YAML
559 lines
18 KiB
YAML
openapi: 3.0.0
|
|
info:
|
|
title: Gotenberg
|
|
version: 6.3.1
|
|
license:
|
|
name: MIT
|
|
url: 'https://github.com/thecodingmachine/gotenberg/blob/master/LICENSE'
|
|
contact:
|
|
url: 'https://github.com/thecodingmachine/gotenberg'
|
|
description: >-
|
|
A Docker-powered stateless API for converting HTML, Markdown and Office
|
|
documents to PDF.
|
|
servers:
|
|
- url: 'http://localhost:3000'
|
|
description: Local server with the default Docker image and port
|
|
paths:
|
|
/convert/html:
|
|
post:
|
|
summary: Convert a given HTML file to PDF
|
|
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.
|
|
|
|
|
|
An example `index.html` file can be as follows:
|
|
|
|
```html
|
|
|
|
<!doctype html>
|
|
|
|
<html lang="en">
|
|
<head>
|
|
<meta charset="utf-8">
|
|
<title>My PDF</title>
|
|
</head>
|
|
<body>
|
|
<h1>Hello world!</h1>
|
|
</body>
|
|
</html>
|
|
|
|
```
|
|
|
|
|
|
You may also add a header and/or a footer in the resulting PDF by
|
|
sending a file named `header.html` and `footer.html` respectively. Both
|
|
the header and the footer files has to be a complete HTML document. An
|
|
example `footer.html` can be as follows:
|
|
|
|
```html
|
|
|
|
<html>
|
|
<head>
|
|
<style>
|
|
body {
|
|
font-size: 8rem;
|
|
margin: 4rem auto;
|
|
}
|
|
</style>
|
|
</head>
|
|
<body>
|
|
<p>
|
|
<span class="pageNumber"></span> of <span class="totalPages"></span>
|
|
</p>
|
|
</body>
|
|
</html>
|
|
|
|
```
|
|
|
|
|
|
The following classes will allow you to inject printing values in your
|
|
document:
|
|
|
|
- `date`: Formatted print date.
|
|
|
|
- `title`: Document title.
|
|
|
|
- `pageNumber`: Current page number.
|
|
|
|
- `totalPage`: Total pages in the document.
|
|
|
|
|
|
There are some limitations with header and footer files:
|
|
|
|
- JavaScript is not executed.
|
|
|
|
- External resources are not loaded.
|
|
|
|
- The CSS properties are independant of the ones used in the
|
|
`index.html` file.
|
|
|
|
- `footer.html` CSS properties override the ones from `header.html`.
|
|
|
|
- Only fonts installed in the Docker image are loaded (see the fonts
|
|
section)
|
|
|
|
- Images only work using a `base64` encoded source, e.g. `<img
|
|
src="data:image/png;base64, iVBORw0K... />`
|
|
|
|
- `background-color` and `color` CSS properties require an additional
|
|
`-webkit-print-color-adjust: exact` CSS property in order to work.
|
|
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'
|
|
/convert/url:
|
|
post:
|
|
summary: Convert the contents of a given URL to PDF
|
|
description: >-
|
|
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.
|
|
requestBody:
|
|
required: true
|
|
description: >-
|
|
The URL conversion request has to be a `multipart/form-data` request
|
|
that includes a `remoteURL`. 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'
|
|
/convert/markdown:
|
|
post:
|
|
summary: Convert a Markdown file to PDF
|
|
description: >-
|
|
Send an HTML file called `index.html` as a multipart form request and
|
|
embed a markdown file into the HTML file using the Golang template
|
|
function `toHTML`, the API will convert the markdown and embed it into
|
|
the HTML this way and render the resulting page. Markdown conversion
|
|
works almost exactly the same way as HTML conversion, therefore 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.
|
|
|
|
|
|
An example `index.html` file can be as follows:
|
|
|
|
```html
|
|
|
|
<!doctype html>
|
|
|
|
<html lang="en">
|
|
<head>
|
|
<meta charset="utf-8">
|
|
<title>My PDF</title>
|
|
</head>
|
|
<body>
|
|
{{ toHTML .DirPath "file.md" }}
|
|
</body>
|
|
</html>
|
|
|
|
```
|
|
|
|
|
|
Whereas your `file.md` file in the same level would be like:
|
|
|
|
```md
|
|
|
|
# Title
|
|
|
|
Content
|
|
|
|
```
|
|
|
|
|
|
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.
|
|
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'
|
|
/convert/office:
|
|
post:
|
|
summary: Convert an Office document to PDF
|
|
description: >-
|
|
Send one or more Office documents and get the resulting PDF file by
|
|
merging all the files. The following file extensions are accepted:
|
|
|
|
- `.txt`
|
|
|
|
- `.rtf`
|
|
|
|
- `.fodt`
|
|
|
|
- `.doc`
|
|
|
|
- `.docx`
|
|
|
|
- `.odt`
|
|
|
|
- `.xls`
|
|
|
|
- `.xlsx`
|
|
|
|
- `.ods`
|
|
|
|
- `.ppt`
|
|
|
|
- `.pptx`
|
|
|
|
- `.odp`
|
|
|
|
|
|
All files will be merged into a single PDF.
|
|
|
|
> **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.
|
|
requestBody:
|
|
content:
|
|
multipart/form-data:
|
|
schema:
|
|
$ref: '#/components/schemas/OfficeConvertRequestBody'
|
|
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'
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties: {}
|
|
/convert/merge:
|
|
post:
|
|
summary: Merge multiple PDFs into a single PDF
|
|
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.
|
|
requestBody:
|
|
content:
|
|
multipart/form-data:
|
|
schema:
|
|
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
|
|
resultFilename:
|
|
type: string
|
|
example: output.pdf
|
|
description: >-
|
|
If provided, the API will return the resulting PDF file with
|
|
the given filename. Otherwise a random filename is used.
|
|
required:
|
|
- files
|
|
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'
|
|
/ping:
|
|
get:
|
|
summary: Your GET endpoint
|
|
tags: []
|
|
responses:
|
|
'200':
|
|
description: The API is working fine.
|
|
operationId: ''
|
|
description: >-
|
|
A simple endpoint to use as a healthcheck for the API availability with
|
|
a simple request.
|
|
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.
|
|
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.
|
|
resultFilename:
|
|
type: string
|
|
example: output.pdf
|
|
description: >-
|
|
If provided, the API will return the resulting PDF file with the
|
|
given filename. Otherwise a random filename is used.
|
|
required:
|
|
- files
|
|
MarkdownConvertRequestBody:
|
|
title: Markdown 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.
|
|
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.
|
|
resultFilename:
|
|
type: string
|
|
example: output.pdf
|
|
description: >-
|
|
If provided, the API will return the resulting PDF file with the
|
|
given filename. Otherwise a random filename is used.
|
|
required:
|
|
- files
|
|
URLConvertRequestBody:
|
|
title: URL Conversion Request Body
|
|
type: object
|
|
properties:
|
|
remoteURL:
|
|
type: string
|
|
example: 'https://google.com'
|
|
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.
|
|
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.
|
|
resultFilename:
|
|
type: string
|
|
example: output.pdf
|
|
description: >-
|
|
If provided, the API will return the resulting PDF file with the
|
|
given filename. Otherwise a random filename is used.
|
|
required:
|
|
- remoteURL
|
|
OfficeConvertRequestBody:
|
|
title: Office 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
|
|
pageRanges:
|
|
type: string
|
|
example: 1-3
|
|
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**.
|
|
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.
|
|
resultFilename:
|
|
type: string
|
|
example: output.pdf
|
|
description: >-
|
|
If provided, the API will return the resulting PDF file with the
|
|
given filename. Otherwise a random filename is used.
|
|
required:
|
|
- files
|
|
MergeFilesRequestBody:
|
|
title: Merge Files 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
|
|
resultFilename:
|
|
type: string
|
|
example: output.pdf
|
|
description: >-
|
|
If provided, the API will return the resulting PDF file with the
|
|
given filename. Otherwise a random filename is used.
|
|
required:
|
|
- files
|
|
securitySchemes: {}
|
|
responses:
|
|
SuccessfulPDF:
|
|
description: Resulting PDF file from the conversion.
|
|
content:
|
|
application/pdf:
|
|
schema:
|
|
type: string
|
|
format: binary
|