Registry / observability / swagger-stats

swagger-stats

JSON →
library0.99.7jsnpmunverified

Swagger-stats is a Node.js library for API telemetry and Application Performance Monitoring (APM). It traces REST API calls and responses, collecting performance, health, and usage statistics per API operation. It supports popular Node.js frameworks including Express, Fastify, Koa, Hapi, and Restify, detecting API operations based on Express routes or an optional OpenAPI (Swagger) specification. Key differentiators include a built-in telemetry UI for immediate monitoring, out-of-the-box integration with Prometheus/Grafana for monitoring and alerting, and Elasticsearch/Kibana for detailed API analytics. The current stable version is 0.99.7, indicating it's actively developed and approaching a 1.0 release, with a cadence of regular bug fixes and dependency updates, alongside occasional feature enhancements. It provides granular metrics to identify problematic endpoints, errors, and performance bottlenecks.

npm install swagger-stats
INSTALL
IMPORT
SIG · SWAGGER-STATS
S
swagger-stats
observabilityjavascriptv0.99.7
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

swaggerStats
import swaggerStats from 'swagger-stats'; // Or for CommonJS: const swaggerStats = require('swagger-stats');
import { swaggerStats } from 'swagger-stats';
The default export is the main swaggerStats object. While the package supports CommonJS, ESM is recommended for new projects.
swaggerStats.express
import swaggerStats from 'swagger-stats'; app.use(swaggerStats.express(options)); // Or for CommonJS: const swaggerStats = require('swagger-stats'); app.use(swaggerStats.express(options));
app.use(require('swagger-stats').middleware(options));
Use `swaggerStats.express` (or `swaggerStats.koa`, `swaggerStats.hapi`, etc.) for framework-specific middleware initialization, not a generic `middleware` function.
swaggerStats.get) (/swagger-stats
import swaggerStats from 'swagger-stats'; app.use(swaggerStats.express({ name: 'my-api', uriPath: '/swagger-stats' }));
app.get('/swagger-stats', swaggerStats.get());
The telemetry UI and API endpoints are typically served as part of the middleware initialization (e.g., `swaggerStats.express`), which exposes them on the configured `uriPath`. Direct routing to `swaggerStats.get()` is generally not required for the default UI.

Sets up an Express application with swagger-stats middleware, exposing basic API telemetry, a built-in UI, and Prometheus metrics.

import express from 'express'; import swaggerStats from 'swagger-stats'; import swaggerSpec from './swagger.json'; // Replace with your OpenAPI spec path const app = express(); const PORT = process.env.PORT || 3000; // Basic Express route app.get('/api/hello', (req, res) => { res.json({ message: 'Hello from API!' }); }); // Integrate swagger-stats middleware app.use(swaggerStats.express({ name: 'My API Service', version: '1.0.0', swaggerSpec: swaggerSpec, // Optional: Provide your OpenAPI specification uriPath: '/swagger-stats', // Default path for UI and metrics hostname: 'localhost', port: PORT, // Uncomment and configure for authentication if needed // authentication: true, // onAuthenticate: (req, username, password) => { // return username === 'admin' && password === 'admin'; // }, })); app.listen(PORT, () => { console.log(`Server running on http://localhost:${PORT}`); console.log(`Swagger-stats UI available at http://localhost:${PORT}/swagger-stats`); console.log(`Prometheus metrics available at http://localhost:${PORT}/swagger-stats/metrics`); });
Debug
Known issues
breakingThe `prom-client` package was converted from a direct dependency to a peer dependency. You must now explicitly install `prom-client` in your project.
fix
Install `prom-client` manually: `npm install prom-client` or `yarn add prom-client`. Ensure its version is within the `>=10 <=14` range specified by swagger-stats.
affects: >=0.95.19
gotchaThe internal dependency on the deprecated `request` package was replaced with `axios`. While this is an internal change, it's good practice to be aware of dependency updates for security and compatibility.
fix
No direct fix for user code, but be aware that if your project had implicit dependencies or complex module resolution tied to `request` being present, this change could subtly affect that setup. Ensure `axios` is compatible within your environment.
affects: >=0.99.5
gotchaVersion `0.99.1` introduced a full switch to a new UX for the built-in telemetry UI. This might affect custom UI configurations, styling, or expectations of the dashboard layout.
fix
Review your `swagger-stats` configuration related to UI customization. If you relied on specific DOM structures or CSS classes for custom branding/integration, these might require updates. Consult the latest documentation for UX configuration options.
affects: >=0.99.1
breakingFor Elasticsearch 7.X, swagger-stats now supports data type `flattened` for request/response bodies. This is an improvement but implies changes in how data is stored and queried in Elasticsearch, potentially breaking existing Kibana dashboards or queries.
fix
If using Elasticsearch for API analytics, review your Kibana visualizations and queries after upgrading to ensure compatibility with the new `flattened` data type. Update existing dashboards as needed, particularly those inspecting request/response body content.
affects: >=0.95.18
Errors
Common errors & fixes
Error: Cannot find module 'prom-client'
`prom-client` is a peer dependency and must be installed explicitly in your project, but it is missing.
fix
Run `npm install prom-client` or `yarn add prom-client` in your project directory.
API Responses page in built-in Telemetry UI is not responding (or slow) with ~1000 endpoints
The built-in UI experienced performance issues when displaying a very large number of API endpoints.
fix
This issue was specifically addressed in `v0.99.2`. Upgrade `swagger-stats` to `0.99.2` or later to leverage performance improvements for the UI.
body response show duplicate data (in Elasticsearch)
Prior versions might have stored body responses inefficiently, leading to duplicate data when querying in Elasticsearch.
fix
Upgrade to `swagger-stats` `0.95.18` or later. This version introduces support for Elasticsearch 7.X `flattened` data types, which addresses this issue and improves storage efficiency. Re-index or clear old data in Elasticsearch if needed.
Authentication not working on /swagger-stats/ux or Hapi authentication issues
Bugs in authentication mechanisms were present in earlier versions for both the built-in UI and Hapi framework integration.
fix
Upgrade to `swagger-stats` `0.99.1` or later, as several authentication-related bugs were fixed in this release, including Hapi-specific issues and general UI protection.
Upgrade
Version history
0.99.7latest on npm
Audit
Dependencies
prom-clientrequiredPrometheus client for metrics exposure. Required peer dependency.
Agent activity
24 hits · last 30 days
node
22
OpenAI (training)
1
Resources
swagger-stats — npm install swagger-stats · libregistry