From f4b6867594fba6b812885f6325124e9b7a68429f Mon Sep 17 00:00:00 2001 From: shuhanmirza Date: Tue, 16 Jan 2024 17:07:43 +0600 Subject: [PATCH] Update documentation --- README.md | 61 +++++++++++++++++++++++++++++++++++++++++-------------- 1 file changed, 46 insertions(+), 15 deletions(-) diff --git a/README.md b/README.md index 81b7c8c..2f38b6b 100644 --- a/README.md +++ b/README.md @@ -1,18 +1,20 @@ -# SpringBooTex +# SimplePdfGenAPI -SpringBooTex is a PDF Generator REST Service that can be deployed out of the box. It can generate PDFs from LaTex and HTML Templates. It supports variable and file embeddings. +SimplePdfGenAPI is a PDF Generator REST Service that can be deployed out of the box. It can generate PDFs from LaTeX and HTML Templates. It supports variable setting and file/image embeddings. -Under the hood, it uses [pdfTeX / pdfLaTeX](https://tug.org/applications/pdftex) to create a PDF from a .tex file. For generating PDFs from HTML templates it uses [openhtmltopdf](https://github.com/danfickle/openhtmltopdf) and Thymeleaf. +Under the hood, it uses [pdfLaTeX](https://tug.org/applications/pdftex) to create a PDF from LaTeX template. For generating PDFs from HTML templates it uses [openhtmltopdf](https://github.com/danfickle/openhtmltopdf) and Thymeleaf. ## Getting Started -You can download the source code for SpringBooTex by running `git clone github.com/shuhanmirza/SpringBooTex` in your terminal. +You can download the source code for SimplePdfGenAPI by running `git clone github.com/shuhanmirza/SimplePdfGenAPI` in your terminal. + After that, you can run `docker-compose up --build`. - -SpringBooTex will run as an REST service by default on port 10800; + +SimplePdfGenAPI will run as an REST service by default on port 10800; ## Generating PDFs PDF's are generated by sending an HTTP POST request to the endpoint "/api/generate-pdf" with a JSON payload: -``` + +```json { "templateType": "LATEX | HTML", "templateSourceType": "BASE64", @@ -23,16 +25,45 @@ PDF's are generated by sending an HTTP POST request to the endpoint "/api/genera "responseType": "JSON | OCTET_STREAM | PDF" } ``` +### templateType +It denotes the type of the provided template. Currently, it supports LATEX and HTML. + +### templateSourceType +It denotes the type of source of the template. Currently, it only accepts the template string in BASE64 format. + +### templateSource +Source of the template. + +For LaTeX, you have to put the variables between two `%` s, such as `%FOOD%`. SimplePdfGenAPI will replace the words denoted in such style with your desired values declared in `stringMap` and `listMap`. For embedding external files, you have to provide the file name and the source URL in the `fileUrlMap`. + +For HTML, SimplePdfGenAPI uses Thymeleaf under the hood. So, you have to follow the notation of Thymeleaf and provide the values in `stringMap` and `listMap`. + +### stringMap +If your template has some single value variables, you can put the values of these variables as key-value map here. + +### listMap +Your template can have some variables that depict list values. You may need this if you are generating something like receipts. +You can make put your lists here. + +### fileUrlMap +For LaTeX templates, you may need to embed an image into the PDF. You can add the URL of the image here. SimplePdfGenAPI downloads the files stated in fileUrlMap before compiling. You have to put the file's name in the key and the URL in the map's value. + +For HTML templates, if you want to instruct the PDF generator to choose a specific font, you can add the URL to that here. You have to put the name of the font family in the key and the the the URL source of the `.ttf` file in the value of the map. + +### responseType +SimplePdfGenAPI can respond with three different media types; `application/json`, `application/octet-stream`, and `application/pdf`. You have to specify what is your desired media type here. Accepted values are `JSON`, `OCTET_STREAM`, and `PDF`. If you choose JSON, the pdf will be given encoded in base64. + +## Example -### Example: Generating a PDF from a latex template +### Generating a PDF from a latex template -See our example LaTex template in [`Doc/example.tex`](https://github.com/shuhanmirza/SpringBooTex/blob/main/Doc/example.tex) +See our example LaTex template in [`Doc/example.tex`](https://github.com/shuhanmirza/SimplePdfGenAPI/blob/main/Doc/example.tex) You can see that, the variables are written between two `%` s. -https://github.com/shuhanmirza/SpringBooTex/blob/49782f4cdd94a3e620f92739f7b37f381c3d77c0/Doc/example.tex#L12-L21 +https://github.com/shuhanmirza/SimplePdfGenAPI/blob/49782f4cdd94a3e620f92739f7b37f381c3d77c0/Doc/example.tex#L12-L21 And the pdf has to embed an image file named `universe.jpg` -https://github.com/shuhanmirza/SpringBooTex/blob/49782f4cdd94a3e620f92739f7b37f381c3d77c0/Doc/example.tex#L37-L38 +https://github.com/shuhanmirza/SimplePdfGenAPI/blob/49782f4cdd94a3e620f92739f7b37f381c3d77c0/Doc/example.tex#L37-L38 Let's prepare the JSON payload. @@ -79,15 +110,15 @@ The JSON payload should look like this, And the generated PDF is ![example-latex.pdf](Doc/example-latex.png) -At first, SpringBooTex downloads all the files mentioned in the `fileUrlMap`. Then, it puts the string and list variables mentioned in `stringMap` and `listMap`. Finally, it compiles the PDF using `pdfLatex`. +At first, SimplePdfGenAPI downloads all the files mentioned in the `fileUrlMap`. Then, it puts the string and list variables mentioned in `stringMap` and `listMap`. Finally, it compiles the PDF using `pdfLatex`. ### Example: Generating a PDF from an HTML template -See our example HTML template in [`Doc/example.html`](https://github.com/shuhanmirza/SpringBooTex/blob/main/Doc/example.html) +See our example HTML template in [`Doc/example.html`](https://github.com/shuhanmirza/SimplePdfGenAPI/blob/main/Doc/example.html) You can see that, the thymeleaf templating has been used in the template. -https://github.com/shuhanmirza/SpringBooTex/blob/543bf20ccad01250303531e9491080804bc48aa6/Doc/example.html#L230-L241 +https://github.com/shuhanmirza/SimplePdfGenAPI/blob/543bf20ccad01250303531e9491080804bc48aa6/Doc/example.html#L230-L241 Like in the earlier example, you must encode the template to a base64 string and prepare a JSON payload. ```JSON @@ -138,7 +169,7 @@ Like in the earlier example, you must encode the template to a base64 string and And the generated PDF is ![example-html.pdf](Doc/example-html.png) -At first, SpringBooTex prepares the HTML using the Thymeleaf template engine. Then it leverages `openhtmltopdf` to render PDF from HTML. If you do not want to provide fonts through HTML, add font source URLs in the `fileUrlMap`. SpringBootex will download and add the fonts during PDF rendering. +At first, SimplePdfGenAPI prepares the HTML using the Thymeleaf template engine. Then it leverages `openhtmltopdf` to render PDF from HTML. If you do not want to provide fonts through HTML, add font source URLs in the `fileUrlMap`. SimplePdfGenAPI will download and add the fonts during PDF rendering. ## Postman Documentation URL https://documenter.getpostman.com/view/4531605/2s9YsNcVGU