diff --git a/docs/openapi.yaml b/docs/openapi.yaml new file mode 100644 index 00000000..7545a445 --- /dev/null +++ b/docs/openapi.yaml @@ -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 + + + + + + + My PDF + + +

Hello world!

+ + + + ``` + + + 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 + + + + + + +

+ of +

+ + + + ``` + + + 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. ` + + + My PDF + + + {{ toHTML .DirPath "file.md" }} + + + + ``` + + + 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