Swagger-ui: Suggestions for improving documentation of initial setup

Created on 16 Mar 2018 · 4Comments · Source: swagger-api/swagger-ui

| Q | A
| ------------------------------- | -------
| Bug or feature request? | Feature request
| Which Swagger/OpenAPI version? | 2.0
| Which Swagger-UI version? | 3.12.1
| How did you install Swagger-UI? | yarn add swagger-ui
| Which browser & version? | N/A
| Which operating system? | Mac OS 10.13

Demonstration API definition

Any

Configuration (browser query string, constructor, config.yaml)

package.json:

{
  "name": "swagger-ui",
  "version": "1.0.0",
  "main": "index.js",
  "license": "MIT",
  "private": true,
  "dependencies": {
    "swagger-ui": "^3.12.1"
  },
  "scripts": {
    "dev": "webpack --mode development",
    "build": "webpack --mode production",
    "start": "webpack-dev-server --mode development --open"
  },
  "devDependencies": {
    "copy-webpack-plugin": "^4.5.1",
    "css-loader": "^0.28.11",
    "html-loader": "^0.5.5",
    "html-webpack-plugin": "^3.0.6",
    "style-loader": "^0.20.3",
    "webpack": "^4.1.1",
    "webpack-cli": "^2.0.12",
    "webpack-dev-server": "^3.1.1"
  }
}

webpack.config.js:

const CopyWebpackPlugin = require('copy-webpack-plugin');
const HtmlWebPackPlugin = require("html-webpack-plugin");
const path = require('path');

const nodeModules = path.resolve(__dirname, 'node_modules');
module.exports = {
    module: {
        rules: [{
            test: /\.html$/,
            use: [{
                loader: "html-loader",
                options: { minimize: true }
            }]
        }, {
            test: /\.css$/,
            use: [{
                loader: "style-loader"
            }, {
                loader: "css-loader",
                options: { minimize: true }
            }]
        }]
    },
    plugins: [
        new HtmlWebPackPlugin({
            template: "./src/index.html",
            filename: "./index.html"
        }),
        new CopyWebpackPlugin([
            { from: nodeModules + '/swagger-ui/dist/oauth2-redirect.html', to: './' }
        ])
    ]
};

src/index.js:

import SwaggerUI from 'swagger-ui';
import 'swagger-ui/dist/swagger-ui.css';
import StandalonePreset from 'swagger-ui/dist/swagger-ui-standalone-preset';

var ui = SwaggerUI({
    dom_id: '#app',
    url: 'my-url',
    oauth2RedirectUrl: 'http://localhost:8080/oauth2-redirect.html',
    plugins: [StandalonePreset],
    layout: 'StandaloneLayout'
    ...
});
ui.initOAuth({
    ...
});

Expected Behavior

Coming from 2.0, I've found 3.0 a little difficult to set up. I'm mentioning a few issues I ran into, in the hope that the docs can be improved to cover them.

In general, it might be helpful to have an example project so we could see how to get started with building swagger-ui. I know this depends on the tools you choose, like webpack, but an example with any toolchain would still be helpful.

A few things I ran into:

I opted to use webpack, with the config file attached. But when I run the production build with yarn run build, I get a warning:

WARNING in entrypoint size limit: The following entrypoint(s) combined asset size exceeds the recommended limit (244 KiB). This can impact web performance.
Entrypoints:
  main (2.1 MiB)
      main.js

Is it really supposed to be that big? I'm not including any other modules besides what you see above.

The installation docs don't mention that you need to load the CSS file, e.g.

import 'swagger-ui/dist/swagger-ui.css';

The installation docs don't mention how to get the full layout, with the logo and header. But the configuration docs do make reference to the Topbar plugin, when describing the "urls" config. So if you want to use "urls", it's not at all clear how to do so. I found it mentioned in an issue that you can add:

import StandalonePreset from 'swagger-ui/dist/swagger-ui-standalone-preset';
SwaggerUI({
    plugins: [StandalonePreset],
    layout: 'StandaloneLayout',

but it would be helpful to see that in the docs.

The docs don't mention how to configure the OAuth2 redirect page (e.g. what should I put on that page, so it can communicate back to swagger-ui?). I ended up copying it into my project from node_modules/swagger-ui/dist/oauth2-redirect.html, which seems to work, but isn't documented.
In swagger-ui 2.x, I could add custom authorizations using the window.swaggerUi.api.clientAuthorizations API. It's not clear whether there's something similar in 3.x, or whether I'd need to write a plugin to do that.