![Reading time](https://www.appknox.com/hs-fs/hubfs/Marketing-template1/clock.png?width=17&height=17&name=clock.png)
This article provides a detailed guide on successfully integrating Swagger UI into web applications using EmberJs as the Javascript framework and Webpack as the module bundler. We will cover the step-by-step process, including any challenges encountered along the way and how we resolved them.
For those unfamiliar with Ember Js or Webpack, we have included introductory sections to get you up to speed. If you’re already familiar with it, feel free to skip directly to the integration steps.
|
Introduction to Swagger UI
Swagger UI is a collection of HTML, JavaScript, and CSS assets that dynamically generate beautiful documentation from a Swagger-compliant API.
Swagger UI allows anyone—be it your development team or your end consumers—to visualize and interact with the API’s resources without having any of the implementation logic in place. It’s automatically generated from your OpenAPI (formerly known as Swagger) Specification, and the visual documentation makes it easy for back-end implementation and client-side consumption.
Introduction to EmberJs
Ember.js is a productive, battle-tested JavaScript framework for building modern web applications. It includes everything you need to build rich UIs that work on any device.
It does so by providing developers with many features essential to managing complexity in modern web applications and an integrated development toolkit that enables rapid iteration.
Introduction to Webpack
Webpack is a static module bundler for modern JavaScript applications. When Webpack processes your application, it internally builds a dependency graph from one or more entry points and then combines every module your project needs into one or more bundles, which are static assets to serve your content from.
How to create a new Ember application?
npx ember new ember-swagger-ui --lang en
This command will create a new directory, ember-swagger-ui, and set up a new Ember application inside of it.
Installing Swagger UI
npm install swagger-ui
Note: We are using the latest version of the library ( 5.17.14 ) at the time of writing this article.
Installing ember-cli-sass
We need to install ember-cli-sass and node-sass to import styles from swagger-ui.
npm install ember-cli-sass node-sass
Adding configuration & import styles
In ember-cli-build.js:
const EmberApp = require('ember-cli/lib/broccoli/ember-app');
module.exports = function (defaults) {
const app = new EmberApp(defaults, {
// Add options here
sassOptions: {
includePaths: ['node_modules/swagger-ui/dist/'],
implementation: require('node-sass'),
},
});
return app.toTree();
};
In styles/app.scss (rename app.css):
@import "swagger-ui";
How to create a wrapper component?
- Go to app/components.
- Create a new folder swagger-ui.
- Inside swagger-ui create files index.html and index.js.
In swagger-ui/index.hbs :
<div ></div>
In swagger-ui/index.js :
import Component from '@glimmer/component';
import { action } from '@ember/object';
import SwaggerUI from 'swagger-ui';
export default class SwaggerUIComponent extends Component {
@action
intializeSwaggerUI(element) {
SwaggerUI({
url: 'https://petstore.swagger.io/v2/swagger.json',
domNode: element,
presets: [SwaggerUI.presets.apis, SwaggerUI.SwaggerUIStandalonePreset],
});
}
}
Add component to templates/application.hbs for preview:
<SwaggerUi />
The Polyfill issue in Webpack 5
Now, if we try to start the application, build compilation will fail, and we will see the following error:
ERROR in ./node_modules/xml/lib/xml.js 1:54-78
Module not found: Error: Can't resolve 'stream' in 'path-to-project/node_modules/xml/lib'
BREAKING CHANGE: webpack < 5 used to include polyfills for node.js core modules by default.
This is no longer the case. Verify if you need this module and configure a polyfill for it.
If you want to include a polyfill, you need to:
- add a fallback 'resolve.fallback: { "stream": require.resolve("stream-browserify") }'
- install 'stream-browserify'
If you don't want to include a polyfill, you can use an empty module like this:
resolve.fallback: { "stream": false }
resolve 'stream' in 'path-to-project/node_modules/xml/lib'
Parsed request is a module
using description file: path-to-project/node_modules/xml/package.json (relative path: ./lib)
Field 'browser' doesn't contain a valid alias configuration
resolve as module
This is because Webpack 4 automatically poly-filled many node APIs in the browser. This was not a great system because it could lead to surprisingly giant libraries getting pulled into your app by accident, and it gave us no control over the exact versions of the polyfills we were using.
So, Webpack 5 removed this functionality. That means we need to make changes to fix this.
Fixing the Polyfill issue in Webpack 5
To fix the build compilation, we need to use the polyfill stream module. Install stream-browserify.
npm install -D stream-browserify
In ember-cli-build.js:
'use strict';
const EmberApp = require('ember-cli/lib/broccoli/ember-app');
module.exports = function (defaults) {
const app = new EmberApp(defaults, {
// Add options here
...
autoImport: {
webpack: {
// extra webpack configuration goes here
resolve: {
fallback: {
stream: require.resolve('stream-browserify'),
},
},
},
},
});
return app.toTree();
};
Now, build the application again, and we should see the build be successful. But if we check the UI in the browser (open and go to http://localhost:4200), it will be blank. Open the console (press F12), and we will see this error:
To fix this, we need to add this to the Webpack configuration:
webpack: {
// extra webpack configuration goes here
node: {
global: true,
},
...
},
Let's build again for the changes to take effect. Now, when we check the browser, the UI still appears to be blank, and there is a new error in the console.
Now, we need to polyfill the buffer module.
npm install -D buffer
In ember-cli-build.js:
const EmberApp = require('ember-cli/lib/broccoli/ember-app');
const webpack = require('webpack');
module.exports = function (defaults) {
const app = new EmberApp(defaults, {
// Add options here
...
autoImport: {
webpack: {
// extra webpack configuration goes here
...
plugins: [
new webpack.ProvidePlugin({
Buffer: ['buffer', 'Buffer'],
}),
],
resolve: {
fallback: {
...
buffer: require.resolve('buffer/'),
},
},
},
},
});
return app.toTree();
};
Now, build again, and we should see the API documentation in the browser.
Conclusion
We have successfully integrated swagger-ui using Webpack 5 and Ember Js. For more configuration and customization, please check out their documentation on GitHub.