swagger-ui-dist

What is swagger-ui-dist?

The swagger-ui-dist package is a distribution of Swagger UI's built files. Swagger UI is a collection of HTML, JavaScript, and CSS assets that dynamically generate beautiful documentation from a Swagger-compliant API. It allows you to visualize and interact with the API’s resources without having any of the implementation logic in place.

What are swagger-ui-dist's main functionalities?

API Documentation

Serve the Swagger UI as a static site in an Express application, providing a visual documentation for your API.

const swaggerUi = require('swagger-ui-dist');
const express = require('express');
const app = express();

app.use('/api-docs', express.static(swaggerUi.getAbsoluteFSPath()));

app.listen(3000, () => {
  console.log('Swagger UI hosted at http://localhost:3000/api-docs');
});

Customization

Customize the Swagger UI by replacing the default URL with your API's URL before serving the HTML file.

const pathToSwaggerUi = require('swagger-ui-dist').absolutePath();
const http = require('http');
const fs = require('fs');

http.createServer((req, res) => {
  if (req.url === '/api-docs') {
    fs.readFile(`${pathToSwaggerUi}/index.html`, 'utf-8', (err, data) => {
      if (err) {
        res.writeHead(404);
        res.end('Not found');
      } else {
        // Customize HTML before sending it
        const result = data.replace('https://petstore.swagger.io/v2/swagger.json', 'url_to_your_api.json');
        res.writeHead(200, {'Content-Type': 'text/html'});
        res.end(result);
      }
    });
  }
}).listen(8080);

Other packages similar to swagger-ui-dist

redoc

ReDoc is an open-source tool that generates API reference documentation from OpenAPI/Swagger definitions. It offers a two-panel, responsive UI and aims for simplicity and readability. Compared to swagger-ui-dist, ReDoc provides a different visual style and may be preferred for its clean, responsive design.

swagger-ui-express

swagger-ui-express is an npm package that allows you to serve auto-generated swagger-ui generated API docs from express, based on a swagger.json file. The package integrates Swagger UI with the Express framework, making it easier to embed within an Express application. It is similar to swagger-ui-dist but tailored specifically for Express.js applications.

swagger-editor-dist

swagger-editor-dist is a distribution of Swagger Editor, which is a web-based editor for editing OpenAPI/Swagger specifications. It is similar to swagger-ui-dist in that it is also a Swagger tool, but it focuses on editing and creating specifications rather than displaying them.

README

Swagger UI Dist

Anonymized analytics

SwaggerUI Dist uses Scarf to collect anonymized installation analytics. These analytics help support the maintainers of this library and ONLY run during installation. To opt out, you can set the scarfSettings.enabled field to false in your project's package.json:

// package.json
{
  // ...
  "scarfSettings": {
    "enabled": false
  }
  // ...
}

Alternatively, you can set the environment variable SCARF_ANALYTICS to false as part of the environment that installs your npm packages, e.g., SCARF_ANALYTICS=false npm install.

API

This module, swagger-ui-dist, exposes Swagger-UI's entire dist folder as a dependency-free npm module. Use swagger-ui instead, if you'd like to have npm install dependencies for you.

SwaggerUIBundle and SwaggerUIStandalonePreset can be imported:

  import { SwaggerUIBundle, SwaggerUIStandalonePreset } from "swagger-ui-dist"

To get an absolute path to this directory for static file serving, use the exported getAbsoluteFSPath method:

const swaggerUiAssetPath = require("swagger-ui-dist").getAbsoluteFSPath()

// then instantiate server that serves files from the swaggerUiAssetPath

For anything else, check the Swagger-UI repository.