feat(SwaggerUI): Add Swagger UI configuration parameters

[aoudiamoncef]

Hi @dmlloyd ,
This PR is related to #5639. I'm waiting for feedbacks
Moncef

[gsmet]

Thanks. I added a couple of suggestions and questions.

[gsmet]

I find it a bit confusing to have an option with an s and one without. It's like that in Swagger UI?

[aoudiamoncef]

Me too, i just copied the original configuration properties names.

[gsmet]

My opinion on this one is that adding things to the URL won't work very well.

I would lean towards trying to find another solution.

[Postremus]

@aoudiamoncef Do you need any help on this pr? I kinda need this feature.

[aoudiamoncef]

I'm agree with @gsmet, we should be able to inject swagger ui configuration at build time.
We are using the pre-packaged webjar of swagger, we couldn't inject a swagger.yml configuration file which could be the best solution.

[Postremus]

I think we are still able to do this, or at least something similar.
The unpackaged swagger-ui is inside "META-INF/swagger-ui-files". Would it be enough to put a generated swagger.yml in this directory?

Alternativly, we could also "just" generate a custom index.html, and configure the swagger-ui this way.

[aoudiamoncef]

@Postremus, we should look at how they inject the config file.

[Postremus]

Ah, I undertstand. The swagger.yml config is staticly included into "swagger-ui.js" during the compilation of the ui.

Another option:
We could generate an index.html, where we configure swagger-ui to load the configuration from a custom configUrl.
We could then just generate a swagger.yml config file at build time, and serve it with quarkus.
The configUrl would point to this static config file.

WDYT?

[aoudiamoncef]

I think that keeping the config properties and inject them inside the html file could be the easiest way to do it.

[gsmet]

@aoudiamoncef any chance you could revisit this by pushing the configuration directly by adjusting the index.html?

It would be similar to what we do here: https://github.com/quarkusio/quarkus/blob/master/extensions/swagger-ui/deployment/src/main/java/io/quarkus/swaggerui/deployment/SwaggerUiProcessor.java#L189 . Except we would push all the configuration properties there.

IMHO, this would be far more future proof.

[aoudiamoncef]

@gsmet, I'll do it ASAP.

[gsmet]

Just a note that you will need to be a bit careful about escaping :).

[aoudiamoncef]

I'm working on pushing configuration to index.html, my idea is to write a Java RegEx to get:

 const ui = SwaggerUIBundle({ // start with this line
        url: "https://petstore.swagger.io/v2/swagger.json",
        dom_id: '#swagger-ui',
        deepLinking: true,
        presets: [
          SwaggerUIBundle.presets.apis,
          SwaggerUIStandalonePreset
        ],
        plugins: [
          SwaggerUIBundle.plugins.DownloadUrl
        ],
        layout: "StandaloneLayout"
      }) // and ends with this one

Then i'll write a kind of string template and inject the configuration Map. Anyone have a better approach ?

[gsmet]

Yeah, I don't think it would be too hard. Just catch SwaggerUIBundle\\(({[^}]+)} with a multiline regexp and it would be safe enough.

With this approach, we could also fix #4766 (see my last comment).

[gsmet]

Additional though: jackson-databind is a dependency of smallrye-openapi. Considering there's a good chance Swagger UI will always be used with openapi, I think you could add the quarkus-jackson extension to handle the JSON generation in the Swagger UI extension.

[aoudiamoncef]

I'm using this RegEx (SwaggerUIBundle\()(.*)(\)) with Dotall and i got:

The idea is to be able to generate a Javascript object using jackson:

ObjectMapper mapper = new ObjectMapper()
        .disable(JsonGenerator.Feature.QUOTE_FIELD_NAMES)
        .enable(SerializationFeature.INDENT_OUTPUT);

We have to replace the group(2) .

[gsmet]

@aoudiamoncef are you making progress? Do you need any help?

[aoudiamoncef]

@gsmet

I'm still working on it but with another approach. It's not a big deal to create a string and replace the matched group.

I'm trying to validate the configurations at build time.

Handling authentication needs more work and we should create tests to avoid regressions in the future.

[aoudiamoncef]

Hi @gsmet,
Updates:
Inject available Swagger UI settings: done
Inject Oauth2 settings: done
Integration test: done (it works as expected on openapi swagger quickstart)
Add Swagger group handling: work in progress(took me more time than i expected).

I'll push my work ASAP

[gsmet]

Cool! Thanks for the heads up.

[aoudiamoncef]

Hi @gsmet,
I'm waiting for feedbacks to improve the code(it works but...) and try to pretty print all the generated configuration.

[gsmet]

Overall, very nice and thorough work, thanks a lot for that!

Could you have a look at my comments?

(sorry for the late review)

[gsmet]

Could we initialize this one statically?

[gsmet]

Same here?

[aoudiamoncef]

@gsmet, i did the requested changes. I'm waiting for your feedbacks.

[gsmet]

Hi Moncef,

Sorry it took me so long to get back to you.

The PR seems broken, I had to change this in the test:

public class CustomConfigTest {

    @RegisterExtension
    static final QuarkusUnitTest config = new QuarkusUnitTest()
            .withConfigurationResource("application-custom-config.properties");

but then the tests are failing anyway.

I think it won't fly to generate the URIs in the config as you somehow need to use httpRootPathBuildItem.adjustPath() on the paths as we do it in the processor. I would probably move all the JSON object building logic to a proper method in the processor.

Then there are other minor things that could be improved but I think we need that to be addressed first.

[aoudiamoncef]

Hi @gsmet,
I'll update the PR ASAP, tests passed few months ago, but i should write better tests.
I remember @phillip-kruger proposal to fuse SwaggeUI extension with OpenApi one. It could make sense with GROUPS, OpenApi extension have to know about this, in order to create supplied GROUPS.

Thanks

[phillip-kruger]

When I suggested that we merge the two, there was concerns that maybe we want to add support for other UIs. I still think we can merge and add support for other UIs via config, as there will not be many (if ever more than one or two). This will make things easier to maintain I think.

[wtrocki]

Maybe other editors could be a separate issue once this one is merged?
Things like Apicurio/Apicurito will be an amazing addition as they can support other schemas.

[matus-m]

Hi guys, what is the state of this MR? We would love to get support for swagger-ui showing multiple openapi files (dropdown in header) for which we need to be able to specify urls attribute of the Swagger ui config.

{url: "<url1>", name: "<name1>"},{url: "<url2>", name: "<name2>"}

I understand that this MR would allow that among other things.
thanks[[m56

[phillip-kruger]

Hi all.
I am looking to get this into smallrye. So far the plan is to allow creating a index html using a basic template and some options. w.d.y.t ?

[matus-m]

any solution that would allow customization of the swagger config options is fine. Right now there is no way how to customize it(I tried adding a webfilter that would modify the html response, but the swagger-ui is server via vertx...). Not sure how long the integration w smallrye would take. We will probably create a custom extension (based on this MR)in the meantime as we need it rather urgently. Thanks for the effort, will keep an eye on this.

[aoudiamoncef]

Hi all,
I'll try to finish this PR ASAP.
I'm sorry but with my current daily work, I haven't a lot of free time to work on open source projects.

[phillip-kruger]

@aoudiamoncef i have added this to SmallRye and will pull that into Quarkus soon.

[phillip-kruger]

#12782 will supersede and close this.