Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

[Feature Request] Swagger UI integration/example #65

Open
netthier opened this issue Jun 15, 2023 · 10 comments
Open

[Feature Request] Swagger UI integration/example #65

netthier opened this issue Jun 15, 2023 · 10 comments
Labels
enhancement New feature or request help wanted Extra attention is needed

Comments

@netthier
Copy link

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.
@Wicpar Wicpar added enhancement New feature or request help wanted Extra attention is needed labels Jun 16, 2023
@kaujea
Copy link

kaujea commented Jun 21, 2023

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.

@Wicpar
Copy link
Collaborator

Wicpar commented Jun 21, 2023

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

@kaujea kaujea mentioned this issue Jun 22, 2023
Closed
@kaujea
Copy link

kaujea commented Jun 22, 2023

@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.

@LehMaxence
Copy link

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.

@Wicpar
Copy link
Collaborator

Wicpar commented Aug 14, 2023

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.

@LehMaxence
Copy link

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.

@Wicpar
Copy link
Collaborator

Wicpar commented Aug 15, 2023 •
edited
Loading

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.

@Wicpar
Copy link
Collaborator

Wicpar commented Sep 23, 2023

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.

@devmaxde
Copy link

devmaxde commented Jan 17, 2024 •
edited
Loading

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

@daniel7grant
Copy link

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).

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
enhancement New feature or request help wanted Extra attention is needed
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
6 participants
@Wicpar @daniel7grant @devmaxde @netthier @LehMaxence @kaujea