3 minutes
This text offers an in depth information on efficiently integrating Swagger UI into net functions utilizing EmberJs because the Javascript framework and Webpack because the module bundler. We’ll cowl the step-by-step course of, together with any challenges encountered alongside the best way and the way we resolved them.
For these unfamiliar with Ember Js or Webpack, we have now included introductory sections to get you on top of things. For those who’re already aware of it, be at liberty to skip on to the combination steps.
Introduction to Swagger UI
Swagger UI is a group of HTML, JavaScript, and CSS property that dynamically generate stunning documentation from a Swagger-compliant API.
Swagger UI permits anybody—be it your growth crew or your finish shoppers—to visualise and work together with the API’s sources with out having any of the implementation logic in place. It’s robotically generated out of your OpenAPI (previously often called Swagger) Specification, and the visible documentation makes it straightforward for back-end implementation and client-side consumption.
Introduction to EmberJs
Ember.js is a productive, battle-tested JavaScript framework for constructing trendy net functions. It consists of the whole lot it is advisable to construct wealthy UIs that work on any system.
It does so by offering builders with many options important to managing complexity in trendy net functions and an built-in growth toolkit that permits speedy iteration.
Introduction to Webpack
Webpack is a static module bundler for contemporary JavaScript functions. When Webpack processes your utility, it internally builds a dependency graph from a number of entry factors after which combines each module your challenge wants into a number of bundles, that are static property to serve your content material from.
The way to create a brand new Ember utility?
npx ember new ember-swagger-ui --lang en
This command will create a brand new listing, ember-swagger-ui, and arrange a brand new Ember utility inside it.
Putting in Swagger UI
npm set up swagger-ui
Notice: We’re utilizing the newest model of the library ( 5.17.14 ) on the time of writing this text.
Putting in ember-cli-sass
We have to set up ember-cli-sass and node-sass to import types from swagger-ui.
npm set up ember-cli-sass node-sass
Including configuration & import types
In ember-cli-build.js:
const EmberApp = require('ember-cli/lib/broccoli/ember-app');
module.exports = operate (defaults) {
const app = new EmberApp(defaults, {
// Add choices right here
sassOptions: {
includePaths: ['node_modules/swagger-ui/dist/'],
implementation: require('node-sass'),
},
});
return app.toTree();
};
In types/app.scss (rename app.css):
@import "swagger-ui";
The way to create a wrapper part?
- Go to app/parts.
- Create a brand new folder swagger-ui.
- Inside swagger-ui create information index.html and index.js.
In swagger-ui/index.hbs :
In swagger-ui/index.js :
import Part from '@glimmer/part';
import { motion } from '@ember/object';
import SwaggerUI from 'swagger-ui';
export default class SwaggerUIComponent extends Part {
@motion
intializeSwaggerUI(ingredient) {
SwaggerUI({
url: 'https://petstore.swagger.io/v2/swagger.json',
domNode: ingredient,
presets: [SwaggerUI.presets.apis, SwaggerUI.SwaggerUIStandalonePreset],
});
}
}
Add part to templates/utility.hbs for preview:
{ { page-title "Swagger UI"}}
The Polyfill challenge in Webpack 5
Now, if we attempt to begin the applying, construct compilation will fail, and we’ll see the next error:
ERROR in ./node_modules/xml/lib/xml.js 1:54-78
Module not discovered: Error: Cannot resolve 'stream' in 'path-to-project/node_modules/xml/lib'BREAKING CHANGE: webpack < 5 used to embrace polyfills for node.js core modules by default.
This is no longer the case. Confirm if you want this module and configure a polyfill for it.If you need to embrace a polyfill, you want to:
- add a fallback 'resolve.fallback: { "stream": require.resolve("stream-browserify") }'
- set up 'stream-browserify'If you do not need to embrace 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
utilizing description file: path-to-project/node_modules/xml/bundle.json (relative path: ./lib)
Discipline 'browser' would not include a legitimate alias configuration
resolve as module
It’s because Webpack 4 robotically poly-filled many node APIs within the browser. This was not an amazing system as a result of it may result in surprisingly large libraries getting pulled into your app accidentally, and it gave us no management over the precise variations of the polyfills we have been utilizing.
So, Webpack 5 eliminated this performance. Which means we have to make modifications to repair this.
Fixing the Polyfill challenge in Webpack 5
To repair the construct compilation, we have to use the polyfill stream module. Set up stream-browserify.
npm set up -D stream-browserify
In ember-cli-build.js:
'use strict';const EmberApp = require('ember-cli/lib/broccoli/ember-app');module.exports = operate (defaults) {
const app = new EmberApp(defaults, {
// Add choices right here
...
autoImport: {
webpack: {
// additional webpack configuration goes right here
resolve: {
fallback: {
stream: require.resolve('stream-browserify'),
},
},
},
},
});
return app.toTree();
};
Now, construct the applying once more, and we must always see the construct achieve success. But when we verify the UI within the browser (open and go to http://localhost:4200), it is going to be clean. Open the console (press F12), and we’ll see this error:
To repair this, we have to add this to the Webpack configuration:
webpack: {
// additional webpack configuration goes right here
node: {
world: true,
},
...
},
Let’s construct once more for the modifications to take impact. Now, once we verify the browser, the UI nonetheless seems to be clean, and there’s a new error within the console.
Now, we have to polyfill the buffer module.
npm set up -D buffer
In ember-cli-build.js:
const EmberApp = require('ember-cli/lib/broccoli/ember-app');
const webpack = require('webpack');module.exports = operate (defaults) {
const app = new EmberApp(defaults, {
// Add choices right here
...
autoImport: {
webpack: {
// additional webpack configuration goes right here
...
plugins: [
new webpack.ProvidePlugin({
Buffer: ['buffer', 'Buffer'],
}),
],
resolve: {
fallback: {
...
buffer: require.resolve('buffer/'),
},
},
},
},
});return app.toTree();
};
Now, construct once more, and we must always see the API documentation within the browser.
Conclusion
We’ve efficiently built-in swagger-ui utilizing Webpack 5 and Ember Js. For extra configuration and customization, please take a look at their documentation on GitHub.