mirror of
https://github.com/gotenberg/gotenberg.git
synced 2026-08-11 18:02:14 +01:00
Add the first version of the OpenAPI documentation
This commit is contained in:
Burak Karakan
558
docs/openapi.yaml
Normal file
558
docs/openapi.yaml
Normal file
@@ -0,0 +1,558 @@
|
||||
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
|
||||
Reference in New Issue
Block a user