{"id":16233,"library":"swagger-stats","title":"API Telemetry and Monitoring for Node.js","description":"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.","status":"active","version":"0.99.7","language":"javascript","source_language":"en","source_url":"https://github.com/slanatech/swagger-stats","tags":["javascript","api","observability","telemetry","node","express","koa","hapi","fastify"],"install":[{"cmd":"npm install swagger-stats","lang":"bash","label":"npm"},{"cmd":"yarn add swagger-stats","lang":"bash","label":"yarn"},{"cmd":"pnpm add swagger-stats","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Prometheus client for metrics exposure. Required peer dependency.","package":"prom-client","optional":false}],"imports":[{"note":"The default export is the main swaggerStats object. While the package supports CommonJS, ESM is recommended for new projects.","wrong":"import { swaggerStats } from 'swagger-stats';","symbol":"swaggerStats","correct":"import swaggerStats from 'swagger-stats';\n// Or for CommonJS:\nconst swaggerStats = require('swagger-stats');"},{"note":"Use `swaggerStats.express` (or `swaggerStats.koa`, `swaggerStats.hapi`, etc.) for framework-specific middleware initialization, not a generic `middleware` function.","wrong":"app.use(require('swagger-stats').middleware(options));","symbol":"swaggerStats.express","correct":"import swaggerStats from 'swagger-stats';\napp.use(swaggerStats.express(options));\n// Or for CommonJS:\nconst swaggerStats = require('swagger-stats');\napp.use(swaggerStats.express(options));"},{"note":"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.","wrong":"app.get('/swagger-stats', swaggerStats.get());","symbol":"swaggerStats.get) (/swagger-stats","correct":"import swaggerStats from 'swagger-stats';\napp.use(swaggerStats.express({ \n  name: 'my-api',\n  uriPath: '/swagger-stats' \n}));"}],"quickstart":{"code":"import express from 'express';\nimport swaggerStats from 'swagger-stats';\nimport swaggerSpec from './swagger.json'; // Replace with your OpenAPI spec path\n\nconst app = express();\nconst PORT = process.env.PORT || 3000;\n\n// Basic Express route\napp.get('/api/hello', (req, res) => {\n  res.json({ message: 'Hello from API!' });\n});\n\n// Integrate swagger-stats middleware\napp.use(swaggerStats.express({\n  name: 'My API Service',\n  version: '1.0.0',\n  swaggerSpec: swaggerSpec, // Optional: Provide your OpenAPI specification\n  uriPath: '/swagger-stats', // Default path for UI and metrics\n  hostname: 'localhost',\n  port: PORT,\n  // Uncomment and configure for authentication if needed\n  // authentication: true,\n  // onAuthenticate: (req, username, password) => {\n  //   return username === 'admin' && password === 'admin';\n  // },\n}));\n\napp.listen(PORT, () => {\n  console.log(`Server running on http://localhost:${PORT}`);\n  console.log(`Swagger-stats UI available at http://localhost:${PORT}/swagger-stats`);\n  console.log(`Prometheus metrics available at http://localhost:${PORT}/swagger-stats/metrics`);\n});\n","lang":"typescript","description":"Sets up an Express application with swagger-stats middleware, exposing basic API telemetry, a built-in UI, and Prometheus metrics."},"warnings":[{"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.","message":"The `prom-client` package was converted from a direct dependency to a peer dependency. You must now explicitly install `prom-client` in your project.","severity":"breaking","affected_versions":">=0.95.19"},{"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.","message":"The 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.","severity":"gotcha","affected_versions":">=0.99.5"},{"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.","message":"Version `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.","severity":"gotcha","affected_versions":">=0.99.1"},{"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.","message":"For 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.","severity":"breaking","affected_versions":">=0.95.18"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Run `npm install prom-client` or `yarn add prom-client` in your project directory.","cause":"`prom-client` is a peer dependency and must be installed explicitly in your project, but it is missing.","error":"Error: Cannot find module 'prom-client'"},{"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.","cause":"The built-in UI experienced performance issues when displaying a very large number of API endpoints.","error":"API Responses page in built-in Telemetry UI is not responding (or slow) with ~1000 endpoints"},{"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.","cause":"Prior versions might have stored body responses inefficiently, leading to duplicate data when querying in Elasticsearch.","error":"body response show duplicate data (in Elasticsearch)"},{"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.","cause":"Bugs in authentication mechanisms were present in earlier versions for both the built-in UI and Hapi framework integration.","error":"Authentication not working on /swagger-stats/ux or Hapi authentication issues"}],"ecosystem":"npm"}