Swagger-ui: Integrate Swagger-UI into project

[fractalocity]

I followed these instructions; probably the best Instructions i've seen anywhere pertaining to swagger (and clearest), https://idratherbewriting.com/learnapidoc/pubapis_swagger.html#create-a-swagger-ui-display
When i run the nodejs project on my local machine it runs fine; i can go to the '/swagger' route and see the swagger-ui. However when i publish this to the server it can't find the 'page'.

Per the instruction above, i am supposed to do the following:

1. download the dist folder (https://github.com/swagger-api/swagger-ui)
2. copy the contents of the dist folder into your projects (copied all files into the project directory where the project swagger.yaml file existed ... ./app/swagger/swagger.yaml)
3. modify the content of the index.html file so it points to your swagger.yaml file:
   // Build a system const ui = SwaggerUIBundle({ url: "swagger.yaml", // <-- modified this line dom_id: '#swagger-ui', docExpansion: 'none', deepLinking: true, presets: [ SwaggerUIBundle.presets.apis, SwaggerUIStandalonePreset ], plugins: [ SwaggerUIBundle.plugins.DownloadUrl ], layout: "StandaloneLayout" })
4. in the app.js file include the following code (route to swagger UI)
   //app.use('/swagger', express.static('./api/swagger'));
   var path = require('path');
   app.use('/swagger', express.static(path.join(__dirname + '/api/swagger')));

I'll probably end up muddling through this on my own but doesn't kill to post the question. Reading articles online is at times minefield because you find too many ways to do the same thing and it's also at times difficult to tell what resources (node package) are needed.

I am guessing either step #3 or #4 is wrong or i am missing an node package. The swagger file itself works fine when tested with the swagger editor (is valid). If i figure out the issue i'll post it.

[shockey]

Hey @fractalocity! Sorry you're having issues.

The way you're calling and serving Swagger-UI looks sane. I did notice that you said you put the UI files in /app/swagger/ in step 2, but your Express server snippet in step 4 refers to /api/swagger. Maybe that was a typo in your message?

If you modified the URL, it might be worth it to use a path that starts with a forward slash. It looks like you're serving everything at /swagger - if so, you should be able to change your url to /swagger/swagger.yaml. I'm not sure that will fix anything, but it can't hurt to be more precise with the path.

If everything works for you locally, but fails on the server - my guess would be that there's something going wrong when you're deploying to your server. Can you check your server, to confirm that the Swagger-UI files are where you expect?

[fractalocity]

You are right. I went ahead and switched the forward slash to a double back slash and published to the server and it works. I've been working a good portion of the day testing out all the wrong things. The final solution was:

1. download the zip folder from (https://github.com/swagger-api/swagger-ui)
2. with the zip file you will find a 'dist' folder. copy all files from the 'dist' folder into your project (into the folder/directory where your swagger.yaml file is located)
3. open the index.html file and change the 'url' in the following code to point to your swagger file
   const ui = SwaggerUIBundle({ url: "swagger.yaml", // <-- modified this line **** dom_id: '#swagger-ui', docExpansion: 'none', deepLinking: true, presets: [ SwaggerUIBundle.presets.apis, SwaggerUIStandalonePreset ], plugins: [ SwaggerUIBundle.plugins.DownloadUrl ], layout: "StandaloneLayout" })
4. go to your app.js file and type in the following line
   app.use('/swagger', express.static('api\swagger\'));
   note: step 4 assumes the following directory structure
   -> Project_folder/app.js
   -> Project_folder/api/swagger/
5. run your node.js project: if you type '/swagger' after the base path, you should now see the swagger UI
   (ex: http://localhost:1337/swagger/)

Again most of this came from the website mentioned above ... just added some to the explanation.
Thanks again Shockey for all the help. Helped out a ton.

[shockey]

Awesome! Glad I could help.

Closing!

[brianupskill]

@shockey Does the Apache 2.0 license allow me to copy the dist folder to use it to display my API spec in production software?

[shockey]

@brianupskill you'd need to consult a lawyer to discuss the specifics of your use case - we can't provide that for you here 😄

More generally, here's a plain-English summary of the Apache 2.0 license: https://tldrlegal.com/license/apache-license-2.0-(apache-2.0)

[lock[bot]]

Locking due to inactivity.
This is done to avoid resurrecting old issues and bumping long threads with new, possibly unrelated content.
If you think you're experiencing something similar to what you've found here: please open a new issue, follow the template, and reference this issue in your report.
Thanks!