使用express-oas-generator生成Swagger文档时POST无Payload文档求助

Hey Lucas, I’ve definitely dealt with this exact headache using express-oas-generator before—there’s nothing more confusing than having a POST endpoint show up in your Swagger docs without any hint of the required payload! Let me share the fixes that worked for me and other developers who ran into the same issue:

1. Confirm you’re using body parsers before the generator #

The tool can’t detect request payloads unless Express is parsing them first. Make sure you’ve added express.json() and (if you need form data support) express.urlencoded() middleware prior to initializing express-oas-generator:

const express = require('express');
const expressOasGenerator = require('express-oas-generator');
const app = express();

// Body parsers must come first!
app.use(express.json());
app.use(express.urlencoded({ extended: true }));

// Now initialize the generator
expressOasGenerator.init(app, {
  // Your config options here
});

2. Manually define payload schemas when auto-detection fails #

Auto-detection can struggle with complex or nested payloads. You can explicitly set the request body schema directly in your route handler using the req.oas object provided by the generator:

app.post('/api/orders', (req, res) => {
  // Define the expected payload structure
  req.oas.schema({
    body: {
      type: 'object',
      required: ['items', 'shippingAddress'],
      properties: {
        items: {
          type: 'array',
          items: {
            type: 'object',
            properties: {
              productId: { type: 'string' },
              quantity: { type: 'number', minimum: 1 }
            }
          }
        },
        shippingAddress: {
          type: 'object',
          properties: {
            street: { type: 'string' },
            city: { type: 'string' },
            zipCode: { type: 'string' }
          }
        }
      }
    }
  });

  // Your route logic here
  res.status(201).json({ orderId: '12345' });
});

3. Ensure your test requests include valid, complete payloads #

express-oas-generator builds schemas from real incoming requests. If your Postman tests were sending empty bodies, invalid JSON, or partial payloads, the generator might not have captured the full schema. Try sending a complete, valid payload multiple times to trigger the tool to record it.

4. Check for middleware conflicts or route order issues #

If you have middleware that modifies the request body (like sanitizers or validators) running before the generator, it can interfere with payload detection. Make sure express-oas-generator is initialized right after body parsers but before any other route-specific middleware.

5. Update the package to the latest version #

Older versions of express-oas-generator had known bugs with payload detection, especially for nested objects. Run npm update express-oas-generator to get the latest fixes—this resolved the issue for many developers in the project’s GitHub issues.

If none of these steps work, sharing a minimal snippet of your route setup and generator configuration would help the community dig deeper!

内容的提问来源于stack exchange，提问作者Lucas_Santos