Swagger-ui: Plans for publishing package with built assets?

[ksmithut]

Long time user of swagger-ui, love the work done here. I also love the new work with v3. One major change for me was that the built source is no longer published to npm (noted in your .npmignore file. I think this is a good thing for people who plan to use swagger-ui in their own build process. I am, however, looking for a prebuilt page that has it all built already. I would love to just install a swagger-ui-dist package or something and just serve up a folder from there as a static directory and have everything just work (relative filepaths and such). Are there plans for distributing something like that in another package?

[shockey]

Hey @ksmithut, thanks for the input.

We chose to publish only our core dist file (dist/swagger-ui.js) to NPM for v3. It's a prebuilt file, but it does not pack its dependencies into itself, as opposed to our bundle file, which does.

This decision was based on the assumption that if you're using NPM to install a module, your build tools have some method of providing the module's external dependencies.

What does your build pipeline look like? I'm interested in hearing more about your use case.

PS: You can use a Git submodule today to consume our bundled dist file from the repository, if you'd like.

[ksmithut]

It was not a build pipeline, it was used like this:

const path = require('path')
const express = require('express')

const PATH_TO_SWAGGER_UI = path.dirname(require.resolve('swagger-ui'))
const app = express()

// There's some middleware here that set the `?url=/path/to/swagger.json`
// to auto populate the url input at the top of the page
// Also a handler to serve up the swagger.json
app.use('/docs', express.static(PATH_TO_SWAGGER_UI))

app.listen(8000)

It is kind of silly relying on the prebuilt version, but it worked really well, and allowed me to self host it without setting up any sort of build pipeline. I'm fine setting up a build pipeline for this one package, but I would probably do it in a separate package, something like swagger-ui-prebuilt or something like that so that it can be included in projects ready made. The other option might be to just install this module via npm git repo linking instead of from the npm registry, because it looks like there are already some built assets in the repo.

Feel free to close this issue if you feel like the published prebuilt stuff is out of the scope of this project.

[webron]

@ksmithut we're actually looking for community feedback on this. We debated on whether to publish something like that or not. You can understand why maintenance-wise, it's better for us not to do that. However, we're trying to understand how/when people would use it differently. Like you said, there's a fairly simple alternative to it. We also have some thoughts on how to do things differently.

Not closing the ticket just yet, as we're looking to hear more from users.

[ksmithut]

Sounds good :) and no worries if it's not in the best interest of the project. It's not too difficult to just build it in whatever project it was going to be served from. The particular project we were trying to add this into was an API only service, so adding in a completely new build pipeline would have been a little overkill, but we'll likely just set up our own pipeline in the meantime.

[feorlen]

I suspect this is why I can no longer use Swagger UI installed via npm with 3.x. I was installing the package and then copying the dist directory to the location I need it. This worked with 2.2.10, but now it doesn't.

I don't need a development environment for Swagger UI, I'm only using npm because the project I'm setting this up for does it this way for dependency management. It needs to be able to install and configure all its necessary components, and then Swagger UI is accessible (dist directory) the same way as its other static web content.

I don't know anything about npm beyond updating package.json to install what I need. I'm only using Swagger UI to display an existing API, not for generating code.

[shockey]

Similar discussion going on for Swagger-Editor here: https://github.com/swagger-api/swagger-editor/issues/1235

[feorlen]

@shockey Thanks for the reference. Do you know of an intention to change this? I was nearly done integrating Swagger UI for our project, and then the new version was released that does things entirely differently.

[shockey]

@feorlen, we're considering it! It's clear that this is something people relied on in 2.x. I'm going to take a look at how much weight it would add to the module sometime today.

Everyone: for the time being, if you're using Git for your project and want to get the full dist folder without having to check it into source control manually, take a look at using Git submodules.

[vlindhol]

Seconding this, I'm running a backend service that runs on express.js and would like to serve up the swagger UI as documentation for internal development. Since I'm not bundling anything for the browser I would like to avoid having to use webpack, just a static folder with the files would be great. Alternatively some express middleware that does the same thing would work.

[feorlen]

I wish I could add a reaction to @shockey's self-assign. Patiently awaiting lovely new updates! :) Thank you for looking into it.

[danderson00]

The simplicity of npm install swagger-ui, expose static route to the dist folder and you're done far outweighs any downsides of publishing the full bundle. It would be more than acceptable to publish this as a separate npm package that includes swagger-ui as a dependency.

The product loses value without this feature.

[shockey]

Proposed solution!

We're planning to begin maintaining a second module for the project, whose contents mirror the dist folder.

@danderson00 @feorlen @vlindhol @ksmithut: will any of you _not_ have your needs served by this solution?

[feorlen]

Awesome! As long as I can drop the dist directory somewhere, that's exactly what I'm looking for. Thank you!

[danderson00]

@shockey Sounds great! Thanks for the update!

[vlindhol]

Great stuff!

[shockey]

Everyone - the entire dist folder has been published as swagger-ui-dist on npm. Please open a new ticket if there are any lingering problems around this use case.

Thanks for your input, and thanks for using Swagger!