Standalone Swagger UI guide for non-node users

[virgo47]

Complicated install?

I know it will sound lame, but when I tested Swagger UI like two years ago I copied some static content, configured it a bit and was done. Today I'm lost in the installation documentation, not knowing where to start, Download button is never downloading but sending me to another page, etc.

When I tried dev environment from this page https://swagger.io/docs/open-source-tools/swagger-ui/development/setting-up/ I ended up on gyp error (I guess I have to install that Python 2.x).

When I get finally here https://www.npmjs.com/package/swagger-ui it suggests npm install ... (and one has to know the site to find it). But that command alone does not help.

When I try https://github.com/swagger-api/swagger-ui/blob/master/docs/usage/installation.md I'm lost right away.

I feel like I have to be node/npm master. I casually do Angular, but I have no idea how to get Swagger up and running in some standalone mode. There seems to be some hope on stackoverflow, but I remember easier start with Swagger UI before.

How can we help?

Step by step guide without assuming that I know node/npm would be welcome. If I create REST API I don't have to be well oriented in node ecosystem. I'm surprised that integration Swagger into Spring Boot is currently easier than to run it standalone with some specification as a parameter.

[lcahlander]

I am unable to compile swagger-ui. I get the following error while running npm install

make: *** [Release/obj.target/binding/src/binding.o] Error 1
gyp ERR! build error 
gyp ERR! stack Error: `make` failed with exit code: 2
gyp ERR! stack     at ChildProcess.onExit (/Users/lcahlander/IdeaProjects/swagger-ui/node_modules/node-gyp/lib/build.js:258:23)
gyp ERR! stack     at ChildProcess.emit (events.js:197:13)
gyp ERR! stack     at Process.ChildProcess._handle.onexit (internal/child_process.js:254:12)
gyp ERR! System Darwin 18.2.0
gyp ERR! command "/usr/local/Cellar/node/11.8.0/bin/node" "/Users/lcahlander/IdeaProjects/swagger-ui/node_modules/node-gyp/bin/node-gyp.js" "rebuild" "--verbose" "--libsass_ext=" "--libsass_cflags=" "--libsass_ldflags=" "--libsass_library="
gyp ERR! cwd /Users/lcahlander/IdeaProjects/swagger-ui/node_modules/node-sass
gyp ERR! node -v v11.8.0
gyp ERR! node-gyp -v v3.6.2
gyp ERR! not ok 
Build failed with error code: 1
npm ERR! code ELIFECYCLE
npm ERR! errno 1
npm ERR! [email protected] postinstall: `node scripts/build.js`
npm ERR! Exit status 1
npm ERR! 
npm ERR! Failed at the [email protected] postinstall script.
npm ERR! This is probably not a problem with npm. There is likely additional logging output above.

npm ERR! A complete log of this run can be found in:
npm ERR!     /Users/lcahlander/.npm/_logs/2019-01-29T17_06_41_782Z-debug.log

[daniel-kun]

Just adding my 2c, after I abandoned swagger ui out of frustration: I find the installation instructions incomprehensible, too, although I am familiar with node, npm, etc.

I was looking for a simple™ way to generate a standalone webpage with swagger ui, but I was not able to get this to work, since the docs are heading in what feels like 10 directions, but don't follow even one environment from start to finish.

My use case is generating and publishing docs on the web for an API that is served on a device, so there is no cloud environment that I control. So just dropping a folder with html/js/css on a webserver was my goal.

[ano]

That's a common problem with software development process these days, unnecessary complexity.

Standalone Install:

• Download the zip from here https://github.com/swagger-api/swagger-ui/archive/master.zip
• Extract out the dist folder from the zip file. That's the folder with Swagger-UI assets already packaged up for distribution.
• Edit the index.html file in the dist folder to suit your needs

Hope that helps

[Akhi1]

@ano thank you so much sir. I was trying to integrate this swagger-ui into my angular application and there were a couple of examples available on internet but unfortunately they weren't working smoothly with latest angular dependencies. I then imported the files (from dist) that you pointed.. on to my project and small tweaks here and there then got it working. Thanks again!

[cemsbr]

Thank you. We can also delete *.map files to save some space.

[gethari]

@ano thank you so much sir. I was trying to integrate this swagger-ui into my angular application and there were a couple of examples available on internet but unfortunately they weren't working smoothly with latest angular dependencies. I then imported the files (from dist) that you pointed.. on to my project and small tweaks here and there then got it working. Thanks again!

Can you share any sample ?

[ano]

@gethari See index.html example here:

https://gist.github.com/ano/6aa608f2007a3192bc928c14740cfaa6

[gethari]

@gethari See index.html example here:

https://gist.github.com/ano/6aa608f2007a3192bc928c14740cfaa6

Thanks @ano . I've got the swagger working but I ended up in a whole different problem #7062

[ntimpj]

I am trying to make a swagger standalone site. I can build my swagger.json file and it is holding the correct data. I have downloaded the swagger-ui and I have copied the dist folder to become my standalone swagger site. I have placed my generated swagger.json file in the copied dist folder. It continues loading swagger petshop test site. I have even tried to replace all petshop url pointers with my own site, but i doesn't make any difference. What am i overlooking? The documentation is rather internal agreed upon, It's an older REST api that I am documenting, I don't have Laravel or Symphony, it is an older MVC framework. There is no tutorials showing standalone swagger solutions. Please help

[ano]

@ntimpj see index.html here: https://gist.github.com/ano/6aa608f2007a3192bc928c14740cfaa6