feat: pass swagger-ui additional configuration

[ghost]

Porpouse

This PR allows to pass a dynamic configuration to the generated swagger UI. The option that should be used in the plugin configuration in order to accomplish that is uiConfig.

Configuration docs: https://github.com/swagger-api/swagger-ui/blob/master/docs/usage/configuration.md

Implementation

Since there is an issue configuring swagger-ui-dist (that distributes only static files, see swagger-api/swagger-ui#5710) without changing the content of the static assets, the only way to configure the UI with a dynamic external configuration is by editing the index.html file and the script within that loads the swagger ui in the page.

There were two approaches:

1. Intercepting the index.html request on the documentation routes and distributing an altered html file that load swagger UI with the configuration merged with the one passed by the user.
2. Editing the file index.html when the project gets prepared (npm run prepare) in order to retrieving a remote configuration fetched through an XHR request on a designated endpoint.

Since the index.html file was already edited in the prepare stage I went for the second approach. Now a new route under GET documentation/uiConfig gets declared and returns the final ui configuration and the script inside the index page fetches the configuration from that endpoint. Finally the page loads the swagger ui from the given configuration.

Drawbacks

Since there is no way to serialize functions over HTTP and JSON there is no way to pass functions to the parameters of the uiConfig, so only string/object/number configuration keys will be effective. Neither the first alternative implementation allowed to do that (at least without writing the plain function in the HTML file). However I think this is a fair compromise.

Related issues

• Supply additional configuration to swagger-ui #228
• swagger-ui#5710

Others

The npm run test didn't run all the test inside the folder test/ since the regex in the command was working only at the first directory level. Now it runs all the test till the 3rd directory level.

Checklist

• run npm run test and npm run benchmark
• tests and/or benchmarks are included
• documentation is changed or added
• commit message and code follows the Developer's Certification of Origin
  and the Code of conduct

[ghost]

The final configuration passed to the Swagger UI is composed by merging sequentially:

• The default swagger UI configuration
• The user defined configuration
• The {url, oauth2RedirectUrl} configuration

[Fdawgs]

Commit message for 9d96c34 should be test, not feat

[mcollina]

Good work!

[mcollina]

lgtm

[climba03003]

LGTM

I get stuck in your option 1 when I see this feature request. My other consideration was CSP, but updating the index.html in npm run prepare is a good solution without affecting CSP.
Good Approach.

[climba03003]

Just a suggest, will you consider replacing the whole block of <script></script> in index.html? I think you already changed all the content inside it.
It is more simple to use a single replace.

[ghost]

Just a suggest, will you consider replacing the whole block of <script></script> in index.html? I think you already changed all the content inside it.
It is more simple to use a single replace.

Yeah, that can do 😄

[mcollina]

@giovanni-bertoncelli so we are waiting for a bit more change.

[ghost]

@giovanni-bertoncelli so we are waiting for a bit more change.

Yes. I'll replace the <script> and the package json in the next days..

[ghost]

Ok. I've:

• Fixed the package.json npm run test with quotes (as @climba03003 suggested)
• Replaced entirely the <script> tag (as @climba03003 suggested)
• Renamed the unit test

(Sorry for the double github account, they are both mine)

[mcollina]

lgtm

[ghost]

Any chance that this will be released soon? :)

[Eomm]

Releasing 👍

[ghost]

Sorry, I've seen the release but downloading with npm the resulting static/ folder contains the old content... 🤔

[Eomm]

mmm the script was updated
https://unpkg.com/browse/[email protected]/lib/util/prepare-swagger-ui.js

and it seems the pre-publish did not run:

fastify-swagger/package.json

Line 7 in 9d87a5f

"prepare": "node lib/util/prepare-swagger-ui",

I can release a fix this evening CEST if someone can't do it earlier

[ghost]

Ok @Eomm is there any error in the package.json definition then?

[mcollina]

I've released v4.1.1, try that.

[ghost]

Yeah, now it's fine 🤷🏻‍♂️
Thanks @mcollina