redoc-express - npm Package Compare versions

Comparing version 2.1.2 to 2.1.3

dist/index.d.ts

@@ -0,3 +1,4 @@
+import { Request, Response } from 'express';
 import { Ioption } from './redoc-html-template';
-declare function redocExpressMiddleware(options?: Ioption): any;
+declare function redocExpressMiddleware(options?: Ioption): (req: Request, res: Response) => void;
 export default redocExpressMiddleware;

dist/index.js

@@ -9,3 +9,3 @@ "use strict";
     }; }
-    return function middleware(req, res) {
+    return function middleware(_req, res) {
         res.type('html');
@@ -12,0 +12,0 @@ res.send((0, redoc_html_template_1.redocHtml)(options));

package.json

 {
   "name": "redoc-express",
-  "version": "2.1.2",
-  "description": "Express Middleware for OpenAPI/Swagger-generated API Reference Documentation",
+  "version": "2.1.3",
+  "description": "Lightweight Express middleware for serving interactive ReDoc API documentation from OpenAPI/Swagger specs. TypeScript support, 100% test coverage, ES5 compatible.",
   "main": "dist/index.js",
@@ -9,5 +9,5 @@ "types": "dist/index.d.ts",
     "format": "prettier --write \"**/*.ts\"",
-    "lint": "eslint \"**/*.ts\"",
-    "lint:fix": "eslint \"**/*.ts\" --fix",
-    "test": "jest",
+    "lint": "NODE_OPTIONS=--no-warnings=MODULE_TYPELESS_PACKAGE_JSON eslint \"**/*.ts\"",
+    "lint:fix": "NODE_OPTIONS=--no-warnings=MODULE_TYPELESS_PACKAGE_JSON eslint \"**/*.ts\" --fix",
+    "test": "NODE_OPTIONS=--no-warnings=ExperimentalWarning jest",
     "build": "tsc",
@@ -24,3 +24,17 @@ "prepublishonly": "npm run lint && npm run test && npm run build"
   "keywords": [
-    "redoc-swagger-ui-express-middleware"
+    "redoc",
+    "express",
+    "middleware",
+    "openapi",
+    "swagger",
+    "api-documentation",
+    "api-docs",
+    "documentation",
+    "rest-api",
+    "typescript",
+    "nodejs",
+    "redoc-express",
+    "swagger-ui",
+    "openapi-documentation",
+    "api-reference"
   ],
@@ -32,16 +46,19 @@ "author": "Aung Myo Kyaw",
   },
-  "homepage": "https://github.com/AungMyoKyaw/redoc-express#readme",
+  "homepage": "https://aungmyokyaw.github.io/redoc-express/",
   "devDependencies": {
-    "@types/jest": "^29.5.1",
-    "@types/node": "^20.0.0",
-    "@typescript-eslint/eslint-plugin": "^5.59.2",
-    "@typescript-eslint/parser": "^5.59.2",
-    "eslint": "^8.39.0",
-    "eslint-config-airbnb-base": "^15.0.0",
+    "@types/express": "^5.0.5",
+    "@types/jest": "^30.0.0",
+    "@types/node": "^24.9.2",
+    "@types/supertest": "^6.0.3",
+    "@typescript-eslint/eslint-plugin": "^8.46.2",
+    "@typescript-eslint/parser": "^8.46.2",
+    "eslint": "^9.38.0",
     "eslint-plugin-import": "^2.18.2",
-    "jest": "^29.5.0",
-    "prettier": "^2.8.8",
-    "ts-jest": "^29.1.0",
+    "express": "^5.1.0",
+    "jest": "^30.2.0",
+    "prettier": "^3.6.2",
+    "supertest": "^7.1.4",
+    "ts-jest": "^29.4.5",
     "typescript": "^5.0.4"
   }
 }

README.md

 # [redoc-express][redoc-express]
 
-> Express Middleware for OpenAPI/Swagger-generated API Reference Documentation
+> Lightweight Express middleware for serving interactive ReDoc API documentation from OpenAPI/Swagger specs with full TypeScript support and zero configuration overhead.
 
@@ -9,10 +9,35 @@ [![code style: prettier][prettier]][prettier-url]
 [![License: MIT][license]][license-url]
-[![coverage][coverage]][coverage-url]
+[![coverage badge][coverage]][coverage-url]
+[![TypeScript][typescript-badge]][typescript-url]
+[![tests][tests-badge]][tests-url]
 
+## Features
+
+- 🚀 **Lightweight & Fast** - Minimal overhead, serves static documentation
+- 📝 **Full TypeScript Support** - First-class TypeScript support with complete type definitions
+- ✅ **100% Test Coverage** - Comprehensive test suite with 136 test cases covering all functionality
+- 🎨 **Customizable UI** - Full ReDoc theming and configuration support
+- 🔒 **Secure** - Built-in CSP nonce support for enhanced security
+- 📦 **ES5 Compatible** - Works across all Node.js versions (Node 6+)
+- 🔧 **Zero Config** - Works out of the box with sensible defaults
+- 🧩 **OpenAPI/Swagger** - Support for both OpenAPI 3.0+ and Swagger 2.0 specifications
+
+## Why redoc-express?
+
+**redoc-express** makes it dead simple to add professional API documentation to your Express server. Unlike alternatives:
+- No build tools required
+- Single middleware setup
+- Works with your existing OpenAPI/Swagger spec
+- Highly customizable but requires no configuration to get started
+- Production-ready with 100% code coverage and 136 comprehensive tests
+
 ## Demo
 
 - [Live Demo][live-demo-url]
+- [Product Website][product-website-url]
 
-## Install
+## Quick Start
 
+### Install
+
 ```shell
@@ -24,2 +49,4 @@ npm install redoc-express
 
+### JavaScript/CommonJS
+
 ```javascript
@@ -32,3 +59,3 @@ const express = require('express');
 
-// serve your swagger.json file
+// Serve your OpenAPI/Swagger spec
 app.get('/docs/swagger.json', (req, res) => {
@@ -38,31 +65,40 @@ res.sendFile('swagger.json', { root: '.' });
 
-// define title and specUrl location
-// serve redoc
+// Mount ReDoc middleware
 app.get(
   '/docs',
   redoc({
-    title: 'API Docs',
+    title: 'API Documentation',
+    specUrl: '/docs/swagger.json'
+  })
+);
+
+app.listen(port, () => {
+  console.log(`📚 API docs available at http://localhost:${port}/docs`);
+});
+```
+
+### TypeScript
+
+```typescript
+import express, { Express } from 'express';
+import redoc from 'redoc-express';
+
+const app: Express = express();
+const port = 3000;
+
+// Serve your OpenAPI/Swagger spec
+app.get('/docs/swagger.json', (req, res) => {
+  res.sendFile('swagger.json', { root: '.' });
+});
+
+// Mount ReDoc middleware with TypeScript support
+app.get(
+  '/docs',
+  redoc({
+    title: 'API Documentation',
     specUrl: '/docs/swagger.json',
-    nonce: '', // <= it is optional,we can omit this key and value
-    // we are now start supporting the redocOptions object
-    // you can omit the options object if you don't need it
-    // https://redocly.com/docs/api-reference-docs/configuration/functionality/
     redocOptions: {
       theme: {
         colors: {
-          primary: {
-            main: '#6EC5AB'
-          }
-        },
-        typography: {
-          fontFamily: `"museo-sans", 'Helvetica Neue', Helvetica, Arial, sans-serif`,
-          fontSize: '15px',
-          lineHeight: '1.5',
-          code: {
-            code: '#87E8C7',
-            backgroundColor: '#4D4D4E'
-          }
-        },
-        menu: {
-          backgroundColor: '#ffffff'
+          primary: { main: '#1976d2' }
         }
@@ -74,5 +110,52 @@ }
 
-app.listen(port, () => console.log(`Example app listening on port ${port}!`));
+app.listen(port, () => {
+  console.log(`📚 API docs available at http://localhost:${port}/docs`);
+});
 ```
 
+### Advanced Configuration
+
+```javascript
+app.get(
+  '/docs',
+  redoc({
+    title: 'My API Documentation',
+    specUrl: 'https://api.example.com/openapi.json',
+    nonce: 'random-nonce-123', // Optional: for CSP compliance
+    redocOptions: {
+      theme: {
+        colors: {
+          primary: { main: '#6EC5AB' }
+        },
+        typography: {
+          fontFamily: '"museo-sans", Helvetica, Arial, sans-serif',
+          fontSize: '15px'
+        },
+        menu: { backgroundColor: '#ffffff' }
+      },
+      hideDownloadButton: true,
+      expandResponses: '200,201,400'
+    }
+  })
+);
+```
+
+For all available ReDoc configuration options, see the [official documentation](https://redocly.com/docs/api-reference-docs/configuration/functionality/)
+
+## Configuration Options
+
+| Option | Type | Required | Description |
+|--------|------|----------|-------------|
+| `title` | string | Yes | Title displayed in the browser tab and header |
+| `specUrl` | string | Yes | URL to your OpenAPI/Swagger specification file |
+| `nonce` | string | No | Security nonce for Content Security Policy compliance |
+| `redocOptions` | object | No | [ReDoc configuration options](https://redocly.com/docs/api-reference-docs/configuration/functionality/) |
+
+## Compatibility
+
+- **Node.js**: 6+ (ES5 compatible)
+- **Express**: 4.x, 5.x
+- **OpenAPI**: 3.0+, Swagger 2.0
+- **TypeScript**: 3.5+
+
 ## Development
@@ -86,10 +169,18 @@
 
-### Run Test
+### Run Tests
 
 ```shell
-npm t
+npm test
 ```
 
+### Build
+
+```shell
+npm run build
+```
+
 ## Test Coverage
 
+### Coverage Metrics
+
 | Metric     | Coverage |
@@ -102,14 +193,61 @@ | ---------- | -------- |
 
-**47 comprehensive test cases** covering:
+### Test Suite
 
-- HTML template generation with various configurations
-- Special characters and edge cases handling
-- Middleware functionality and request/response handling
-- Complex nested options and JSON serialization
-- Daily CI/CD test runs with automated issue creation
+**136 comprehensive test cases** organized across 3 test suites:
 
-## Check ReDoc Project for more INFO
+- **Unit Tests - redocHtml** (85+ tests)
+  - HTML structure and DOCTYPE validation
+  - Title handling (unicode, emoji, special characters, extreme lengths)
+  - URL/Spec handling (protocols, authentication, fragments, long URLs)
+  - Nonce validation and CSP compliance
+  - ReDoc options configuration (objects, arrays, numbers, booleans)
+  - JSON serialization and escaping
 
-- [redoc][redoc-url]
+- **Unit Tests - redocExpressMiddleware** (51+ tests)
+  - Express middleware behavior and method ordering
+  - Content-type and response handling
+  - Request/response immutability
+  - Multiple middleware invocations
+  - Edge cases and error handling
 
+- **End-to-End Tests** (26+ tests)
+  - Real-world Express integration scenarios
+  - Concurrent request handling
+  - Multiple API documentation versions
+  - Route isolation and middleware chains
+  - Stress testing with rapid requests
+
+### Test Execution
+
+```bash
+npm test              # Run all 136 tests
+npm test -- --coverage # With coverage report
+npm test -- --watch   # Watch mode during development
+```
+
+All tests pass with **100% code coverage** in approximately **1-2 seconds**.
+
+## FAQ
+
+**Q: Can I use this with TypeScript?**
+A: Yes! Full TypeScript support with included type definitions.
+
+**Q: Does this work with OpenAPI 3.0?**
+A: Yes, both OpenAPI 3.0+ and Swagger 2.0 are supported.
+
+**Q: Is there a performance impact?**
+A: Minimal. The middleware only serves static HTML—no runtime overhead.
+
+**Q: Can I customize the UI colors/fonts?**
+A: Yes, pass `redocOptions` with your theme configuration.
+
+**Q: What Node.js versions are supported?**
+A: Node 6+ (ES5 compiled output). Development requires Node 18.14+.
+
+## Resources
+
+- [ReDoc Documentation][redoc-url]
+- [OpenAPI Specification](https://spec.openapis.org/)
+- [Report Issues](https://github.com/AungMyoKyaw/redoc-express/issues)
+
 ## License
@@ -128,5 +266,10 @@
 [prettier-url]: https://github.com/prettier/prettier
+[typescript-badge]: https://img.shields.io/badge/TypeScript-5.0%2B-blue.svg?style=flat-square
+[typescript-url]: https://www.typescriptlang.org/
 [redoc-url]: https://github.com/Redocly/redoc
 [live-demo-url]: http://redocly.github.io/redoc/
+[product-website-url]: https://aungmyokyaw.github.io/redoc-express/
 [coverage]: https://img.shields.io/badge/coverage-100%25-brightgreen.svg?style=flat-square
 [coverage-url]: #test-coverage
+[tests-badge]: https://img.shields.io/badge/tests-136%20passing-brightgreen.svg?style=flat-square
+[tests-url]: #test-coverage

New alerts

URL strings

Supply chain risk

Package contains fragments of external URLs or IP addresses, which the package may be accessing at runtime.

Found 1 instance in 1 package

Fixed alerts

URL strings

Supply chain risk

Package contains fragments of external URLs or IP addresses, which the package may be accessing at runtime.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

13142

65.58%

Lines of code

48

2.13%

Number of lines in readme file

268

114.4%

Worsened metrics

Dev dependency count

14

27.27%

No dependency changes