Reputation: 2958

Generate PDF from Swagger API documentation

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!

Upvotes: 116

Answers (5)

Caius Jard

Reputation: 74700

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

Ran my swagger enabled netcore API project
Browser appeared with the swaggergen'd "try it out" page, which is pretty enough for the purpose
Hide the tryout buttons: Right clicked "Try it out" >> "Inspect element" >> Add CSS class >> display: none for try-out
PicPick tray icon >> capture >> scrolling window
Click on the content pane of the browser
Note: PP might only be able to scroll the window if the cursor remains hovering over it - at least that's what I found
Wait some time while it repeatedly scrolls, screenshots and stitches the imagery together
Save the result as a PNG
Load Publisher, set a custom page size of (PNG dimensions divided by 96) inches
Insert the image and reset to 100% size
Save as PDF

Upvotes: 0

Irdis

Reputation: 986

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.

Upvotes: 37

Simon

Reputation: 4585

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.

Upvotes: 1