I have used the Swagger UI to display my REST webservices and hosted it on a server.
However this service of Swagger can only be accessed on a particular server. If I want to work offline, does anybody know how I can create a static PDF using the Swagger UI and work with it? Additionally a PDF is easy to share with people who don't have access to the server.
Many thanks!
I figured out a way using https://github.com/springfox/springfox and https://github.com/RobWin/swagger2markup
Used Swagger 2 to implement documentation.
I created a web site https://www.swdoc.org/ that specifically addresses the problem. So it automates swagger.json -> Asciidoc, Asciidoc -> pdf transformation as suggested in the answers. Benefit of this is that you dont need to go through the installation procedures. It accepts a spec document in form of url or just a raw json. Project is written in C# and its page is https://github.com/Irdis/SwDoc
EDIT
It might be a good idea to validate your json specs here: http://editor.swagger.io/ if you are having any problems with SwDoc, like the pdf being generated incomplete.
You can modify your REST project, so as to produce the needed static documents (html, pdf etc) upon building the project.
If you have a Java Maven project you can use the pom snippet below. It uses a series of plugins to generate a pdf and an html documentation (of the project's REST resources).
Please be aware that the order of execution matters, since the output of one plugin, becomes the input to the next:
<plugin>
<groupId>com.github.kongchen</groupId>
<artifactId>swagger-maven-plugin</artifactId>
<version>3.1.3</version>
<configuration>
<apiSources>
<apiSource>
<springmvc>false</springmvc>
<locations>some.package</locations>
<basePath>/api</basePath>
<info>
<title>Put your REST service's name here</title>
<description>Add some description</description>
<version>v1</version>
</info>
<swaggerDirectory>${project.build.directory}/api</swaggerDirectory>
<attachSwaggerArtifact>true</attachSwaggerArtifact>
</apiSource>
</apiSources>
</configuration>
<executions>
<execution>
<phase>${phase.generate-documentation}</phase>
<!-- fx process-classes phase -->
<goals>
<goal>generate</goal>
</goals>
</execution>
</executions>
</plugin>
<plugin>
<groupId>io.github.robwin</groupId>
<artifactId>swagger2markup-maven-plugin</artifactId>
<version>0.9.3</version>
<configuration>
<inputDirectory>${project.build.directory}/api</inputDirectory>
<outputDirectory>${generated.asciidoc.directory}</outputDirectory>
<!-- specify location to place asciidoc files -->
<markupLanguage>asciidoc</markupLanguage>
</configuration>
<executions>
<execution>
<phase>${phase.generate-documentation}</phase>
<goals>
<goal>process-swagger</goal>
</goals>
</execution>
</executions>
</plugin>
<plugin>
<groupId>org.asciidoctor</groupId>
<artifactId>asciidoctor-maven-plugin</artifactId>
<version>1.5.3</version>
<dependencies>
<dependency>
<groupId>org.asciidoctor</groupId>
<artifactId>asciidoctorj-pdf</artifactId>
<version>1.5.0-alpha.11</version>
</dependency>
<dependency>
<groupId>org.jruby</groupId>
<artifactId>jruby-complete</artifactId>
<version>1.7.21</version>
</dependency>
</dependencies>
<configuration>
<sourceDirectory>${asciidoctor.input.directory}</sourceDirectory>
<!-- You will need to create an .adoc file. This is the input to this plugin -->
<sourceDocumentName>swagger.adoc</sourceDocumentName>
<attributes>
<doctype>book</doctype>
<toc>left</toc>
<toclevels>2</toclevels>
<generated>${generated.asciidoc.directory}</generated>
<!-- this path is referenced in swagger.adoc file. The given file will simply
point to the previously create adoc files/assemble them. -->
</attributes>
</configuration>
<executions>
<execution>
<id>asciidoc-to-html</id>
<phase>${phase.generate-documentation}</phase>
<goals>
<goal>process-asciidoc</goal>
</goals>
<configuration>
<backend>html5</backend>
<outputDirectory>${generated.html.directory}</outputDirectory>
<!-- specify location to place html file -->
</configuration>
</execution>
<execution>
<id>asciidoc-to-pdf</id>
<phase>${phase.generate-documentation}</phase>
<goals>
<goal>process-asciidoc</goal>
</goals>
<configuration>
<backend>pdf</backend>
<outputDirectory>${generated.pdf.directory}</outputDirectory>
<!-- specify location to place pdf file -->
</configuration>
</execution>
</executions>
</plugin>
The asciidoctor plugin assumes the existence of an .adoc file to work on. You can create one that simply collects the ones that were created by the swagger2markup plugin:
include::{generated}/overview.adoc[]
include::{generated}/paths.adoc[]
include::{generated}/definitions.adoc[]
If you want your generated html document to become part of your war file you have to make sure that it is present on the top level - static files in the WEB-INF folder will not be served. You can do this in the maven-war-plugin:
<plugin>
<artifactId>maven-war-plugin</artifactId>
<configuration>
<warSourceDirectory>WebContent</warSourceDirectory>
<failOnMissingWebXml>false</failOnMissingWebXml>
<webResources>
<resource>
<directory>${generated.html.directory}</directory>
<!-- Add swagger.pdf to WAR file, so as to make it available as static content. -->
</resource>
<resource>
<directory>${generated.pdf.directory}</directory>
<!-- Add swagger.html to WAR file, so as to make it available as static content. -->
</resource>
</webResources>
</configuration>
</plugin>
The war plugin works on the generated documentation - as such, you must make sure that those plugins have been executed in an earlier phase.
Checkout https://mrin9.github.io/RapiPdf a custom element with plenty of customization and localization feature.
Disclaimer: I am the author of this package
For me the easiest solution was to import swagger (v2) into Postman and then go to the web view. There you can choose "single column" view and use the browser to print to pdf. Not a automated/integrated solution but good for single-use. It handles paper-width much better than printing from editor2.swagger.io, where scrollbars cause portions of the content to be hidden.
I was after something relatively quick and simple, minimal software install. I was looking for something to paste into a word document to show that the API existed; I didn't need any level of interactivity or ability to copypaste operations out.
I already had a piece of software called PicPick, a screenshotting tool that can capture a scrolling window (it scrolls, screenshots and stitches together generating one incredibly tall image)
It also can save as a PDF, but makes a poor job of it, paper-size wise so I passed it through Publisher
display: none for try-out