search

swagger-api / swagger-editor

Swagger Editor
https://editor.swagger.io
Apache License 2.0
8.89k stars 2.25k forks source link

SwaggerEditor@next: expose preview plugins as UMD build fragments #4381

Open char0n opened 1 year ago

char0n commented 1 year ago

There are 4 plugins that provide preview for additional specifications (AsyncAPI, API Design Systems):

We need to export these plugins as UMD fragments to make them available via https://www.unpkg.com/. This will allow use those plugins directly in HTML files without building.

ValeryShvyndzikau commented 8 months ago

Hi @char0n could you please share details about the plans/roadmap to make new plugins available (specifically EditorPreviewAsyncAPIPlugin & SwaggerUIAdapterPlugin) via https://www.unpkg.com/? To have kind of the following definition in the html page and render openAPI & asyncAPI documents

<script src="//unpkg.com/swagger-ui-dist@3.29.0/swagger-ui-bundle.js"></script>
<script src="//unpkg.com/swagger-ui-dist@3.29.0/swagger-ui-standalone-preset.js"></script>
<script src="//unpkg.com/swagger-editor-dist@5.x.x/swagger-editor-standalone-plugins.js"></script>

SwaggerUI({
  url: 'https://openapi.yaml' OR 'https://asyncnapi.yaml'
  dom_id: '#swagger-ui',
  presets: [
    SwaggerUI.presets.apis,
    SwaggerUIStandalonePreset
  ],
  plugins: [
    EditorPreviewAsyncAPIPlugin,
    SwaggerUIAdapterPlugin,
    SwaggerUI.plugins.DownloadUrl,
  ],
  layout: 'StandaloneLayout',
});
char0n commented 8 months ago

Hi @ValeryShvyndzikau,

We will probably not be exposing the UMD build of the plugins as it will bloat the size of the npm package unnecessarily (but it's still under the consideration). There will be a separate project https://github.com/char0n/swagger-ui-multifold that will provide multi-spec SwaggerUI experience.

Without the UMD build fragments of the plugins, the effect that you want to achieve can be achieved in following way by accessing the plugins from SwaggerEditor symbol.

<!DOCTYPE html>
<html >
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <meta name="theme-color" content="#000000" />
    <meta name="description" content="SwaggerUIMultifold" />
    <link rel="stylesheet" href="//unpkg.com/swagger-editor@5.0.0-alpha.86/dist/swagger-editor.css" />
  </head>
  <body style="margin:0; padding:0;">
    <section id="swagger-ui"></section>

    <script src="//unpkg.com/swagger-ui-dist@5.11.0/swagger-ui-bundle.js"></script>
    <script src="//unpkg.com/swagger-ui-dist@5.11.0/swagger-ui-standalone-preset.js"></script>
    <script>
      ui = SwaggerUIBundle({});
      // expose SwaggerUI React globally for SwaggerEditor to use
      window.React = ui.React;
    </script>
    <script src="//unpkg.com/swagger-editor@5.0.0-alpha.86/dist/umd/swagger-editor.js"></script>
    <script>
      SwaggerUIBundle({
        url: 'https://petstore3.swagger.io/api/v3/openapi.json',
        dom_id: '#swagger-ui',
        presets: [
          SwaggerUIBundle.presets.apis,
          SwaggerUIStandalonePreset,
        ],
        plugins: [
          SwaggerEditor.plugins.EditorContentType,
          SwaggerEditor.plugins.EditorPreviewAsyncAPI,
          SwaggerEditor.plugins.EditorPreviewApiDesignSystems,
          SwaggerEditor.plugins.SwaggerUIAdapter,
          SwaggerUIBundle.plugins.DownloadUrl,
        ],
        layout: 'StandaloneLayout',
      });
    </script>
  </body>
</html>

AsyncAPI fixture: https://raw.githubusercontent.com/asyncapi/spec/v2.6.0/examples/streetlights-kafka.yml API Design Systems fixture: https://raw.githubusercontent.com/smizell/api-design-systems/main/example.yml

ValeryShvyndzikau commented 8 months ago

Hi @char0n, it works, BIG THANKS. We are able to introduce asyncapi specs in addition to the openapi ones for our microservices architecture.

char0n commented 8 months ago

Hi @char0n, it works, BIG THANKS. We are able to introduce asyncapi specs in addition to the openapi ones for our microservices architecture.

Cool, be aware that the JavaScript you're downloading now is quite huge as it contains Monaco editor and VSCode API. The reason is that you're not able to tree-shake using unpkg.com. Another thing is that It currently supports only AsyncAPI 2.x and not 3.0. 3.x will be comming soon.