swagger-ui-express vs swagger-jsdoc vs @umijs/openapi
API Documentation Tools Comparison
Search packages..
3 Years
swagger-ui-expressswagger-jsdoc@umijs/openapi
What's API Documentation Tools?

API Documentation Tools are essential for generating, visualizing, and maintaining documentation for APIs (Application Programming Interfaces). These tools help developers create clear and interactive documentation that describes how to use an API, including its endpoints, request/response formats, authentication methods, and error handling. Well-documented APIs improve developer experience, facilitate integration, and enhance collaboration between teams. Tools like swagger-jsdoc and swagger-ui-express integrate with Swagger, a popular framework for API documentation, while @umijs/openapi offers a more modern and feature-rich approach, especially for projects using Umi.js.

Package Weekly Downloads Trend
Github Stars Ranking
Stat Detail
Package
Downloads
Stars
Size
Issues
Publish
License
swagger-ui-express2,275,054
1,48024 kB50a year agoMIT
swagger-jsdoc816,426
1,757712 kB393 years agoMIT
@umijs/openapi13,182
0123 kB04 days agoMIT
Feature Comparison: swagger-ui-express vs swagger-jsdoc vs @umijs/openapi

Integration with Frameworks

  • swagger-ui-express:

    swagger-ui-express is also framework-agnostic but is commonly used with Express.js applications. It serves the Swagger UI, a web-based interface that allows users to explore and interact with your API documentation. It can be easily integrated with swagger-jsdoc to display the documentation generated from JSDoc comments, providing a complete solution for visualizing API endpoints.

  • swagger-jsdoc:

    swagger-jsdoc is framework-agnostic and can be used with any Node.js application. It generates Swagger documentation from JSDoc comments in your code, making it easy to integrate into existing projects without requiring any specific framework. This flexibility allows developers to use it in a wide range of applications, from simple Express servers to more complex architectures.

  • @umijs/openapi:

    @umijs/openapi is designed to work seamlessly with Umi.js, a popular React framework. It leverages Umi's plugin architecture to provide advanced features like automatic code generation, API mocking, and customizable documentation. This makes it a great choice for projects built on the Umi ecosystem.

Documentation Generation

  • swagger-ui-express:

    swagger-ui-express does not generate documentation by itself but serves the Swagger UI, which displays the documentation. It is typically used in conjunction with swagger-jsdoc or other documentation generation tools to provide a visual interface for the API documentation.

  • swagger-jsdoc:

    swagger-jsdoc generates Swagger documentation in real-time by parsing JSDoc comments in your code. It allows for dynamic documentation generation, which means that the documentation is always up-to-date with the code. The tool supports both OpenAPI 2.0 and 3.0, providing flexibility in how the documentation is structured.

  • @umijs/openapi:

    @umijs/openapi provides automated documentation generation based on OpenAPI specifications. It supports both OpenAPI 2.0 and 3.0, allowing for more detailed and structured documentation. The tool also supports customizable templates, making it easy to tailor the documentation to your project's needs.

Customization

  • swagger-ui-express:

    swagger-ui-express provides some customization options for the Swagger UI, including the ability to modify the layout, add custom CSS, and configure the UI components. However, most of the customization is focused on the visual presentation of the documentation rather than the underlying data.

  • swagger-jsdoc:

    swagger-jsdoc allows for customization of the generated Swagger documentation through JSDoc comments. Developers can add custom tags, modify the structure of the generated documentation, and integrate with other tools as needed. However, the level of customization is primarily limited to what can be done through JSDoc comments.

  • @umijs/openapi:

    @umijs/openapi offers extensive customization options, including the ability to modify the generated documentation, customize the API design, and integrate with third-party tools. It also supports plugin development, allowing developers to extend its functionality as needed.

Ease of Use: Code Examples

  • swagger-ui-express:

    Example of swagger-ui-express integration:

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

const swaggerOptions = {
  swaggerDefinition: {
    openapi: '3.0.0',
    info: {
      title: 'API Documentation',
      version: '1.0.0',
    },
  },
  apis: ['./routes/*.js'], // Path to your API docs
};

const swaggerDocs = swaggerJsDoc(swaggerOptions);
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocs));

app.listen(3000, () => {
  console.log('Server is running on http://localhost:3000');
});
  • swagger-jsdoc:

    Example of swagger-jsdoc usage:

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

const swaggerOptions = {
  swaggerDefinition: {
    openapi: '3.0.0',
    info: {
      title: 'API Documentation',
      version: '1.0.0',
    },
  },
  apis: ['./routes/*.js'], // Path to your API docs
};

const swaggerDocs = swaggerJsDoc(swaggerOptions);
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocs));

app.listen(3000, () => {
  console.log('Server is running on http://localhost:3000');
});
  • @umijs/openapi:

    Example of @umijs/openapi integration in a Umi.js project:

    // umi.config.js
export default {
  plugins: [
    '@umijs/openapi',
  ],
  openapi: {
    // OpenAPI configuration
    // ...
  },
};
How to Choose: swagger-ui-express vs swagger-jsdoc vs @umijs/openapi
  • swagger-ui-express:

    Choose swagger-ui-express if you want to serve interactive Swagger UI documentation for your APIs. It works well with any Node.js application and can be easily integrated with swagger-jsdoc to display the documentation generated from your code.

  • swagger-jsdoc:

    Choose swagger-jsdoc if you prefer a simple and flexible way to generate Swagger documentation directly from your JSDoc comments in the code. It is lightweight and easy to integrate into any Node.js application, making it ideal for projects that want to document APIs without a lot of overhead.

  • @umijs/openapi:

    Choose @umijs/openapi if you are working on a modern Umi.js project and need a comprehensive solution that integrates seamlessly with the Umi ecosystem. It offers advanced features like code generation, customizable documentation, and better support for OpenAPI 3.0.

Similar Npm Packages to swagger-jsdoc

swagger-jsdoc is a powerful tool that allows developers to generate Swagger API documentation from JSDoc comments in their code. It simplifies the process of documenting APIs by enabling you to write documentation alongside your code, ensuring that it is always up-to-date with the implementation. This approach helps in maintaining accurate and comprehensive API documentation, which is crucial for both development and collaboration with other teams or external users.

One notable alternative to swagger-jsdoc is swagger-ui-express. This package serves as a middleware for Express applications, allowing you to serve Swagger UI, which provides a visual representation of your API documentation. While swagger-jsdoc focuses on generating the documentation from your code comments, swagger-ui-express is used to display that documentation in a user-friendly interface. Together, they can be used to create a seamless experience for documenting and interacting with your APIs.

For a detailed comparison of these packages, check out the following link: Comparing swagger-jsdoc vs swagger-ui-express.

Similar Npm Packages to @umijs/openapi

@umijs/openapi is a powerful tool designed to facilitate the integration of OpenAPI specifications into UmiJS applications. It allows developers to generate API documentation and client code based on OpenAPI definitions, streamlining the process of building and maintaining APIs. This package is particularly useful for teams that want to ensure their API documentation is always in sync with the actual implementation, promoting better collaboration and understanding among developers and stakeholders.

While @umijs/openapi offers a robust solution for OpenAPI integration, there are other libraries that serve similar purposes. Here are a couple of alternatives:

  • swagger-jsdoc is a popular library that allows developers to generate OpenAPI (formerly known as Swagger) documentation using JSDoc comments in their code. By annotating your code with specific comments, you can automatically generate a comprehensive API documentation file. This approach is particularly beneficial for teams that prefer to keep their documentation close to the code, ensuring that it remains up-to-date as the code evolves. swagger-jsdoc is a great choice if you want to leverage JSDoc for documentation generation and prefer a more code-centric approach.

  • swagger-ui-express is another widely-used library that provides a simple way to serve Swagger UI in an Express application. It allows developers to visualize and interact with their API documentation in a user-friendly interface. By integrating swagger-ui-express with your Express server, you can easily present your API documentation to users and developers, making it easier to understand and test the API endpoints. This library is ideal for those who want to provide a clear and interactive way to explore their API.

To compare these packages, check out the following link: Comparing swagger-jsdoc vs swagger-ui-express.

README for swagger-ui-express

Swagger UI Express

| Statements | Branches | Functions | Lines | | --------------------------- | ----------------------- | ------------------------- | -------------------- | | Statements | Branches | Functions | Lines |

This module allows you to serve auto-generated swagger-ui generated API docs from express, based on a swagger.json file. The result is living documentation for your API hosted from your API server via a route.

Swagger version is pulled from npm module swagger-ui-dist. Please use a lock file or specify the version of swagger-ui-dist you want to ensure it is consistent across environments.

You may be also interested in:

  • swagger-jsdoc: Allows you to markup routes with jsdoc comments. It then produces a full swagger yml config dynamically, which you can pass to this module to produce documentation. See below under the usage section for more info.
  • swagger tools: Various tools, including swagger editor, swagger code gen etc.

Usage

Install using npm:

$ npm install swagger-ui-express

Express setup app.js

const express = require('express');
const app = express();
const swaggerUi = require('swagger-ui-express');
const swaggerDocument = require('./swagger.json');

app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument));

or if you are using Express router

const router = require('express').Router();
const swaggerUi = require('swagger-ui-express');
const swaggerDocument = require('./swagger.json');

router.use('/api-docs', swaggerUi.serve);
router.get('/api-docs', swaggerUi.setup(swaggerDocument));

Open http://<app_host>:<app_port>/api-docs in your browser to view the documentation.

If you want to set up routing based on the swagger document checkout swagger-express-router

swagger-jsdoc

If you are using swagger-jsdoc simply pass the swaggerSpec into the setup function:

// Initialize swagger-jsdoc -> returns validated swagger spec in json format
const swaggerSpec = swaggerJSDoc(options);

app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerSpec));

Swagger Explorer

By default the Swagger Explorer bar is hidden, to display it pass true as the 'explorer' property of the options to the setup function:

const express = require('express');
const app = express();
const swaggerUi = require('swagger-ui-express');
const swaggerDocument = require('./swagger.json');

var options = {
  explorer: true
};

app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument, options));

Custom swagger options

To pass custom options e.g. validatorUrl, to the SwaggerUi client pass an object as the 'swaggerOptions' property of the options to the setup function:

const express = require('express');
const app = express();
const swaggerUi = require('swagger-ui-express');
const swaggerDocument = require('./swagger.json');

var options = {
  swaggerOptions: {
    validatorUrl: null
  }
};

app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument, options));

For all the available options, refer to Swagger UI Configuration

Custom CSS styles

To customize the style of the swagger page, you can pass custom CSS as the 'customCss' property of the options to the setup function.

E.g. to hide the swagger header:

const express = require('express');
const app = express();
const swaggerUi = require('swagger-ui-express');
const swaggerDocument = require('./swagger.json');

var options = {
  customCss: '.swagger-ui .topbar { display: none }'
};

app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument, options));

Custom CSS styles from Url

You can also pass the url to a custom css file, the value must be the public url of the file and can be relative or absolute to the swagger path.

const express = require('express');
const app = express();
const swaggerUi = require('swagger-ui-express');
const swaggerDocument = require('./swagger.json');

var options = {
  customCssUrl: '/custom.css'
};

app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument, options));

You can also pass an array of css urls to load multiple css files.

const express = require('express');
const app = express();
const swaggerUi = require('swagger-ui-express');
const swaggerDocument = require('./swagger.json');

var options = {
  customCssUrl: [
    '/custom.css',
    'https://example.com/other-custom.css'
  ]
};

app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument, options));

Custom JS

If you would like to have full control over your HTML you can provide your own javascript file, value accepts absolute or relative path. Value must be the public url of the js file.

const express = require('express');
const app = express();
const swaggerUi = require('swagger-ui-express');
const swaggerDocument = require('./swagger.json');

var options = {
  customJs: '/custom.js'
};

app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument, options));

You can also pass an array of js urls to load multiple js files.

const express = require('express');
const app = express();
const swaggerUi = require('swagger-ui-express');
const swaggerDocument = require('./swagger.json');

var options = {
  customJs: [
    '/custom.js',
    'https://example.com/other-custom.js'
  ]
};

app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument, options));

It is also possible to add inline javascript, either as string or array of string.

const express = require('express');
const app = express();
const swaggerUi = require('swagger-ui-express');
const swaggerDocument = require('./swagger.json');

var options = {
  customJsStr: 'console.log("Hello World")'
};

app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument, options));

const express = require('express');
const app = express();
const swaggerUi = require('swagger-ui-express');
const swaggerDocument = require('./swagger.json');

var options = {
  customJsStr: [
    'console.log("Hello World")',
    `
    var x = 1
    console.log(x)
    `
  ]
};

app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument, options));

Load swagger from url

To load your swagger from a url instead of injecting the document, pass null as the first parameter, and pass the relative or absolute URL as the 'url' property to 'swaggerOptions' in the setup function.

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

var options = {
  swaggerOptions: {
    url: 'http://petstore.swagger.io/v2/swagger.json'
  }
}

app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(null, options));

To load multiple swagger documents from urls as a dropdown in the explorer bar, pass an array of object with name and url to 'urls' property to 'swaggerOptions' in the setup function.

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

var options = {
  explorer: true,
  swaggerOptions: {
    urls: [
      {
        url: 'http://petstore.swagger.io/v2/swagger.json',
        name: 'Spec1'
      },
      {
        url: 'http://petstore.swagger.io/v2/swagger.json',
        name: 'Spec2'
      }
    ]
  }
}

app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(null, options));

Make sure 'explorer' option is set to 'true' in your setup options for the dropdown to be visible.

Load swagger from yaml file

To load your swagger specification yaml file you need to use a module able to convert yaml to json; for instance yaml.

npm install yaml

const express = require('express');
const app = express();
const swaggerUi = require('swagger-ui-express');
const fs = require("fs")
const YAML = require('yaml')

const file  = fs.readFileSync('./swagger.yaml', 'utf8')
const swaggerDocument = YAML.parse(file)

app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument));

Modify swagger file on the fly before load

To dynamically set the host, or any other content, in the swagger file based on the incoming request object you may pass the json via the req object; to achieve this just do not pass the the swagger json to the setup function and it will look for swaggerDoc in the req object.

const express = require('express');
const app = express();
const swaggerUi = require('swagger-ui-express');
const swaggerDocument = require('./swagger.json');

var options = {}

app.use('/api-docs', function(req, res, next){
    swaggerDocument.host = req.get('host');
    req.swaggerDoc = swaggerDocument;
    next();
}, swaggerUi.serveFiles(swaggerDocument, options), swaggerUi.setup());

Two swagger documents

To run 2 swagger ui instances with different swagger documents, use the serveFiles function instead of the serve function. The serveFiles function has the same signature as the setup function.

const express = require('express');
const app = express();
const swaggerUi = require('swagger-ui-express');
const swaggerDocumentOne = require('./swagger-one.json');
const swaggerDocumentTwo = require('./swagger-two.json');

var options = {}

app.use('/api-docs-one', swaggerUi.serveFiles(swaggerDocumentOne, options), swaggerUi.setup(swaggerDocumentOne));

app.use('/api-docs-two', swaggerUi.serveFiles(swaggerDocumentTwo, options), swaggerUi.setup(swaggerDocumentTwo));

app.use('/api-docs-dynamic', function(req, res, next){
  req.swaggerDoc = swaggerDocument;
  next();
}, swaggerUi.serveFiles(), swaggerUi.setup());

Link to Swagger document

To render a link to the swagger document for downloading within the swagger ui - then serve the swagger doc as an endpoint and use the url option to point to it:

const express = require('express');
const app = express();
const swaggerUi = require('swagger-ui-express');
const swaggerDocument = require('./swagger.json');

var options = {
    swaggerOptions: {
        url: "/api-docs/swagger.json",
    },
}
app.get("/api-docs/swagger.json", (req, res) => res.json(swaggerDocument));
app.use('/api-docs', swaggerUi.serveFiles(null, options), swaggerUi.setup(null, options));

Requirements

  • Node v0.10.32 or above
  • Express 4 or above

Testing

  • Install phantom
  • npm install
  • npm test
npm-compare.com is an independent website designed to help developers choose the most suitable npm packages. We are not affiliated with npm, Inc or npmjs.com, the official website for the npm registry. Please note that npm is a registered trademark of npm, Inc. For more details, please refer to our Terms & Privacy.