| # swagger2markup output fed to asciidoctor-pdf – all via published docker images | |
| # The following is a Makefile command in the root of a web service repo with the following assumptions: | |
| # ./swagger/v1/swagger.json is the swagger definition (created by rswag in my case) | |
| # ./_docs/ is where we want the PDF and intermediate ADOC to live | |
| # The ADOC file is pretty useful, but if you just want the PDF, it's a byproduct you might want to clean up | |
| api_pdf: | |
| docker run –rm -v $(shell pwd):/opt swagger2markup/swagger2markup convert -i /opt/swagger/v1/swagger.json -f /opt/_docs/api-definition | |
| docker run –rm -v $(shell pwd)/_docs:/documents/ asciidoctor/docker-asciidoctor asciidoctor-pdf api-definition.adoc | |
| # To add configuration options for swagger2markup, create a config.properties file and specify with | |
| # -c /opt/config.properties | |
| # asciidoctor-pdf supports pretty extensive styling: | |
| # https://github.com/asciidoctor/asciidoctor-pdf/blob/master/docs/theming-guide.adoc#applying-your-theme |
After you’ve written automated tests (such as with rswag) and provided an interactive swagger-ui reference for your API, you might still have folks who want a static reference document. Rather than copy-pasta that introduces errors, you can create a PDF reference with just a few commands (in a Unix environment; for Windows you’ll have to change the $(shell pwd) bits).
Happily, swagger2markup and asciidoctor both provide public docker images, making it very easy to use them without installation, dependency management, or environment wrangling.
The first time you run this, you’ll be waiting while the images download from Docker Hub, but afterwards you’ll just check to see that the images are up-to-date.
I’m running the above from a multi-purpose Makefile (with make api_pdf), but you can clearly use these lines from other contexts too.
A little deeper
docker pull downloads an image from Docker Hub. By simply giving swagger2markup/swagger2markup and asciidoctor/docker-asciidoctor we pull the latest of these images.
If Docker doesn’t find the image we specify it’ll attempt to download the latest from Docker Hub.
docker run runs a command in a container. --rm tells docker to clean up after itself so that we can run this as often as we want and only the generated files change.
-v $(shell pwd):/opt mounts the local filesystem before the colon to the path after the colon within the container. $(shell pwd) is giving us the current working directory, for for this example, /opt is where it can be found in the container. That means that the container can read the and write within the current working directory.
After the --rm and -v flags, we specify the Docker container we want to use (the same name we pulled with and everything else is the command to execute inside the container.docker pull),
For swagger2markup, we run the convert command, specify the input with the -i parameter. Note that the path is how the file is found inside the container, not where it is in my usual filesystem. The same applies to the file specified with -f, which will be created and given the .adoc extension.
For Asciidoctor, we run the asciidoctor-pdf command, and simply specify the ADOC file. Asciidoctor-pdf looks in the /documents directory, which we’ve mapped to our /_docs directory, and it outputs the PDF to the same.
According to the theming guide, we can add a -a parameter or three to specify a custom theme for the PDF.
Those two lines take advantage of extensive efforts by others, a chunk of bandwidth and computation, and spit out a PDF document of your Swagger API.
