Registry / devops / mongoose-to-swagger

mongoose-to-swagger

library1.5.1jsnpmunverified

Converts Mongoose schema objects to Swagger/OpenAPI schema definitions. Currently at v1.5.1, stable and used in production for many projects. Key differentiator is the simplicity of converting any Mongoose model into a Swagger-compatible JSON schema, extracting description, enum, required fields automatically. Supports custom meta property whitelisting and omission of internal Mongoose fields. Does not support OpenAPI 3.0+ yet (Swagger 2.0 only). Released under MIT.

devops

npm install mongoose-to-swagger

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · MONGOOSE-TO-SWAGGE

mongoose-to-swagger

devopsjavascriptv1.5.1

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

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

default export

✓ import m2s from 'mongoose-to-swagger'

✗ const m2s = require('mongoose-to-swagger')

Package uses CommonJS internally but type definitions declare default export. Both import styles work.

m2s (named)

✓ import { default as m2s } from 'mongoose-to-swagger'

✗ import { m2s } from 'mongoose-to-swagger'

There is no named export; only default export. Use default import.

require

✓ const m2s = require('mongoose-to-swagger')

✗ const { m2s } = require('mongoose-to-swagger')

Destructuring the default export from require returns undefined.

Converts a Mongoose schema with custom meta properties to a Swagger schema definition.

import mongoose from 'mongoose'; import m2s from 'mongoose-to-swagger'; const CatSchema = new mongoose.Schema({ name: { type: String, description: 'Name of the cat' }, color: String, }); const Cat = mongoose.model('Cat', CatSchema); const swaggerSchema = m2s(Cat, { props: ['description'] }); console.log(JSON.stringify(swaggerSchema, null, 2)); // Output: { // "type": "object", // "properties": { // "_id": { "type": "string" }, // "name": { "type": "string", "description": "Name of the cat" }, // "color": { "type": "string" } // } // }

Debug

Known issues

gotchaOnly Swagger 2.0 output; does not generate OpenAPI 3.0 schemas.

fix

Use openapi-to-swagger or manually convert to OpenAPI 3.0. Alternatively, use a library like @nestjs/swagger for OpenAPI 3.0.

affects: <=1.5.1

gotchaSubdocuments and arrays may not produce correct Swagger definitions (e.g., refs not created properly).

fix

Manually inspect and adjust the output for complex schemas. Consider using mongoose-to-openapi for better OpenAPI 3.0 support.

affects: <=1.5.1

gotchaomitMongooseInternals defaults to true, which removes __v and id fields. Setting to false retains them.

fix

Set omitMongooseInternals: false if you need those fields in the output.

affects: >=1.0.0

deprecatedNo updates since 2020; package is in maintenance mode.

fix

Evaluate if it still meets your needs or consider migrating to active forks.

affects: <=1.5.1

Errors

Common errors & fixes

TypeError: m2s is not a function

Using destructured import from require: const { m2s } = require('mongoose-to-swagger')

fix

Use const m2s = require('mongoose-to-swagger') or import m2s from 'mongoose-to-swagger'.

Cannot read property 'schema' of undefined

Passing a plain object instead of a Mongoose Model (instance from mongoose.model()).

fix

Ensure you pass a Mongoose model, e.g., const Cat = mongoose.model('Cat', CatSchema); m2s(Cat);

TypeError: Cannot convert undefined or null to object

Passing null or undefined as the first argument.

fix

Verify the model is defined and not null/undefined.

Upgrade

Version history

1.5.1latest on npm

Audit

Dependencies

mongooserequiredPeer dependency for defining Mongoose models and schemas

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/blugavere/mongoose-to-swagger ↗

packagemongoose-to-swagger ↗

homepagehttps://github.com/blugavere/mongoose-to-swagger#readme ↗