aide [Feature Request] Swagger UI integration/example

Since its most recent release Swagger UI supports OpenAPI 3.1 specs, meaning it can be used to render aide-generated docs. As it offers a few useful features over Redoc, such as a convenient "Try it out" button, it would be interesting to have support for this similar to aide::redoc or at least docs in the form of an example using it. However, the build process seems a bit more involved. While there is a static dist version similar to how Redoc works, it's recommended to use the npm package in conjunction with a tool like webpack instead to save space, as described here. Not sure what the best way to go forward is because of that.

Jun 15 '23 11:06 netthier

Hey! I took a look at this issue and I believe that an integration in aide would fall under the category "serve Swagger UI in a server-side project", for which they recommend the dist bundle (similar to the aide::redoc). I created a proof of concept, based what is done in utoipa. I'd be delighted to open a PR here! I am new to open source so I might require some support to get everything right.

Jun 21 '23 11:06 kaujea

Thank you @kaujea ! There is only an issue with your method: it breaks standalone artifacts since it relies on a folder existing at runtime. I think it would be far simpler as well to include_str each file from the res folder so that it is compile inside of the executable, just like redoc is done right now. If you do that i'll accept the PR

Jun 21 '23 12:06 Wicpar

@Wicpar Fair point. I tried to address the issue, but it got a bit more verbose than I hoped for (esp. I had to resort to a macro). Let me know if you see a better way to achieve this result.

Jun 22 '23 18:06 kaujea

If you're going to integrate swagger-ui code inside this crate, you'll want to abide by their license.

Meaning you'll have to adjust the license of the aide crate to always include the Apache-2.0 license and include sagger-ui's notice in the distributable.

It would also be nice to identify which version of swagger-ui was used in case any bug, vulnerability or security issue was to be discovered inside swagger-ui's code.

My opinion on this is it should be kept as example in the repo and not integrated in the crate to avoid all the above.

Aug 14 '23 14:08 LehMaxence

It is allowed to keep the license only on the relevant sources without changing the aide licence (§4 of the apache 2.0). Just like redoc it might be better to add it as a feature. Version should be available on the ui ? It would be in the sources anyway.

Aug 14 '23 16:08 Wicpar

I am not a lawyer but:

of course, you don't have to change the license of aide's IP (MIT Or Apache-2.0)
including swagger-ui inside the crate, i.e. the distributed file, makes the Apache 2.0 always applicable, and its NOTICE file must be part of the distribution, so the license of the crate becomes (MIT OR Apache-2.0) AND Apache-2.0

You can check unicode-ident as reference of a crate including a third-party work.

Aug 14 '23 16:08 LehMaxence

If we include the source of course it will be attached to the license, either within the source or the folder, and it should be mentionned in the Readme, but the crates license remains the same. If swagger has issues with that they may get in touch with us.

Aug 15 '23 20:08 Wicpar

I'm going to integrate the feature using https://crates.io/crates/swagger-ui, it's a lot more compliant and maintanable as it pulls directly from NPM.

Sep 23 '23 20:09 Wicpar

Why don't you use the Static assets? For example

    <!DOCTYPE html>
    <html>
    <head>
    <link type="text/css" rel="stylesheet" href="https://cdn.jsdelivr.net/npm/[email protected]/swagger-ui.css">
    <title>Axum - Swagger UI</title>
    </head>
    <body>
    <div id="swagger-ui">
    </div>
    <script src="https://cdn.jsdelivr.net/npm/[email protected]/swagger-ui-bundle.js"></script>
    <!-- `SwaggerUIBundle` is now available on the page -->
    <script>
    const ui = SwaggerUIBundle({
        url: '/openapi.json',
    "dom_id": "#swagger-ui",
"layout": "BaseLayout",
"deepLinking": true,
"showExtensions": true,
"showCommonExtensions": true,
oauth2RedirectUrl: window.location.origin + '/docs/oauth2-redirect',
    presets: [
        SwaggerUIBundle.presets.apis,
        SwaggerUIBundle.SwaggerUIStandalonePreset
        ],
    })
    </script>
    </body>
    </html>

This took me like 30min to implement for my own Project

Jan 17 '24 13:01 devmaxde

Hey @Wicpar, did you eventually come up with something regarding this? I would love to have a SwaggerUI integration in aide. If you like, I could put together a PR, based on the other integrations (Redoc, Scalar).

May 15 '24 15:05 daniel7grant

aide aide copied to clipboard

[Feature Request] Swagger UI integration/example

aide
aide copied to clipboard