111

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!

Andriy Ivaneyko
  • 20,639
  • 6
  • 60
  • 82
Aman Mohammed
  • 2,878
  • 5
  • 25
  • 39

5 Answers5

47

Handy way: Using Browser Printing/Preview

  1. Hide editor pane
  2. Print Preview (I used firefox, others also fine)
  3. Change its page setup and print to pdf

enter image description here

Osify
  • 2,253
  • 25
  • 42
  • Simple! The documentation comes out quite well. – ShaTin May 31 '17 at 04:07
  • 1
    You can even choose between two documentation designs as long as there're two Swagger services: https://editor.swagger.io/ (new) and http://editor2.swagger.io (previous)! – naXa stands with Ukraine Dec 21 '17 at 09:10
  • Effective but lossy bcos swagger HTML UI has multiple tabs, for a POST/PUT method's parameters you must choose between the model tab and the example value tab, then in the printed-to-PDF version one of them is forever hidden :( – chrisinmtown Sep 26 '18 at 20:17
  • 1
    This didn't work for me. Each endpoint would get cut off with the end of the page (no matter what page setup I used). The next page would then begin at the top of the next Endpoint block. Maybe something has changed since this answer was written. – Synctrex Jan 08 '20 at 19:20
  • I still see it's workable, you might need to adapt the margin. Try from https://editor.swagger.io/ – Osify Jan 09 '20 at 08:55
35

I figured out a way using https://github.com/springfox/springfox and https://github.com/RobWin/swagger2markup

Used Swagger 2 to implement documentation.

Aman Mohammed
  • 2,878
  • 5
  • 25
  • 39
  • hi, i am also trying to generate offline documentation using swagger.Are you able to generate swagger documentation ?? – Sunil Rk Jun 03 '15 at 08:48
  • yes, i used the example projects and integrated my webservice code in them and was able to generate the documentation. – Aman Mohammed Jun 03 '15 at 10:41
  • 1
    Can you please tell me in short, how i can integrate my web service to examples which you have mentioned above. – Sunil Rk Jun 04 '15 at 06:08
  • The swagger2markup project needs a JSON input of the REST API. If you download that gradle project and change the swagger.json file in that with your API details and then run the Swagger2MarkupConverterTest JUnit method: testSwagger2HtmlConversion, it should generate the HTML for you in the folder build/docs/generated/asciidocAsString of the project. So in other words there are 2 things. 1) First generate the JSON format for your REST API using Swagger Editor. 2) Using that JSON Format, you can use swagger2markup project to produce standalone HTML documentation of the API – Aman Mohammed Jun 05 '15 at 08:54
34

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.

Ewoks
  • 12,285
  • 8
  • 58
  • 67
Irdis
  • 919
  • 9
  • 16
  • 3
    thx, yeah it's pretty nice, I use it for my work projects. I'm thinking of writing some code to support openapi 3.0 on my spare time. – Irdis Sep 10 '19 at 17:46
  • 2
    All glory to the authors of the tools it relies on, ofc – Irdis Sep 10 '19 at 18:11
  • @Irdis I tried using the link. It allows Swagger 2.0 doc to be parsed but the document I am providing is of Open API 3.0 and it is unable to generate the document. – hellowahab Nov 29 '19 at 11:44
  • I tried swagger 3+ - works fine, it shows raw html for remarks though... – Sasha Bond Mar 17 '20 at 21:22
  • 3
    This is a great tool! If you ever have problems like I had (like pdf being generated incomplete), paste your json here: http://editor.swagger.io/ to be automatically validated, fix the issues and you'll be good to go back to swdoc tool and generate it properly this time. – Thales Valias Jul 03 '20 at 18:36
  • 1
    You should add automatic detection of 3.0 spec. – dataman Feb 12 '21 at 16:38
1

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.

Simon
  • 4,395
  • 8
  • 33
  • 50
0

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
Caius Jard
  • 72,509
  • 5
  • 49
  • 80