Swagger-editor: Documentation: Installation / Running

[fireproofsocks]

It would be helpful if the README file included just a few lines about how to install and start this up.

[shockey]

See: https://github.com/swagger-api/swagger-editor#running-locally.

That section is a bit thin, any recommendations on what could be improved?

[fireproofsocks]

I think it might be good to list the perfunctory stuff, e.g. to either download the zip file from Github or outline how to use npm to install the package and run the server. Thanks!

[theigor]

Agreed. For example, the following does not work:

npm i -g http-server
npm i -g swagger-editor
http-server swagger-editor -p 3002

The above results in a 404.
Navigating to the global npm installs, I do not find an index.html but instead I find this in C:\Users\theigor\AppData\Roaming\npm\node_modules\swagger-editor>:

Mode                LastWriteTime         Length Name
----                -------------         ------ ----
d-----        9/22/2017   9:25 AM                dist
d-----        9/22/2017   9:25 AM                node_modules
-a----        9/22/2017   9:25 AM            589 LICENSE
-a----        9/22/2017   9:25 AM          10259 package.json
-a----        9/22/2017   9:25 AM           3077 README.md

If I try to install the package locally, and then npm run start, I do get a server but it's a directory listing with no index.html and /index.html results in a 404. Same thing happens if I try http-server C:\Users\theigor\AppData\Roaming\npm\node_modules\swagger-editor -p 3002 - i get a directory listing with no index.

I'm almost sure I am doing something silly wrong, but the fact that there is no documentation (that I could find) on how to do it _right_ is a problem. Also, if anyone can point to what I am doing wrong, I'd appreciate it.

[shockey]

Hey @theigor!

We actually publish two modules, swagger-editor and swagger-editor-dist. You're correct, this has been undocumented, which _is_ a problem. I just added a section to the README about it (via #1505), which you'll find copied below:

This repository publishes to two different NPM modules:

• swagger-editor is a traditional npm module intended for use in JavaScript web application projects that are capable of resolving dependencies (via Webpack, Browserify, etc).
• swagger-editor-dist is a dependency-free module that includes everything you need to serve Swagger-Editor in a server-side project, or a web project that can't resolve npm module dependencies.

If you want to serve Swagger-Editor with http-server, this should do the trick:

npm i -g http-server
npm i -g swagger-editor-dist
http-server $(npm root -g)/swagger-editor-dist -p 3002

[theigor]

Thanks @shockey! That's great. I don't need webpack for this api but for my future reference, what is the process for getting this running via webpack or something similar? Are you saying I can globally install swagger-editor and start the editor on some port via a script?

[shockey]

what is the process for getting this running via webpack or something similar?

Sure, you'd just import swagger-editor into your project like you would any other module.

I wrote an example React application that illustrates what this looks like with Swagger-UI: https://github.com/shockey/swagger-ui-cra/blob/f71b79125512bf4a159bf7f1b14af3c4d19e1894/src/App.js#L20

Doing the same thing with Swagger-Editor would be very similar.

Are you saying I can globally install swagger-editor and start the editor on some port via a script?

The Swagger-Editor project is a web application/library, so providing an application server to serve the Editor is a bit out of scope for us (though we do have a Docker image that does that, since Docker containers need to expose something to the world).

To sum it up: the swagger-editor module is meant for use within single-page applications, and expects that your project is capable of resolving npm module references. swagger-editor-dist, on the other hand, is for server-side projects and times when you literally just want to serve Swagger-Editor (like you just did with http-server!).

[theigor]

Perfect. Thanks.

[zaynetro]

@shockey Just a recommendation based on your comment: Existence of swagger-editor docker container is not mentioned in any way in the Readme. Having a similar section as in swagger-ui repo would help things significantly (ref: https://github.com/swagger-api/swagger-ui#easy-start--docker)

[shockey]

Thanks @zaynetro, I hadn't realized the omission. I opened a new ticket for that specific bit of documentation 😄