Swagger Express Middleware

Swagger 2.0 middlware and mocks for Express.js

Metadata middleware

Annotates each request with all the relevant information from the Swagger definition. The path, the operation, the parameters, the security requirements - they’re all easily accessible at req.swagger.

Example

This example uses the PetStore.yaml sample Swagger API. If you aren’t familiar with using middleware in Express.js, then read this first.

const util = require('util');
const express = require('express');
const createMiddleware = require('@apidevtools/swagger-express-middleware');

let app = express();

createMiddleware('PetStore.yaml', app, function(err, middleware) {
    // Add the Metadata middleware to the Express app
    app.use(middleware.metadata());

    // Add middleware to display the Swagger metadata as HTML
    app.use(function(req, res, next) {
        res.type('html');
        res.send(util.format('<h1>%s has %d parameters</h1><pre>%s</pre>',
            req.swagger.pathName,
            req.swagger.params.length,
            util.inspect(req.swagger.params)
        ));
    });

    app.listen(8000, function() {
        console.log('Go to http://localhost:8000/pets/Fido/photos/12345');
    });
});

Run the above example and then try browsing to http://localhost:8000/pets/Fido and http://localhost:8000/pets/Fido/photos/12345. You will see different metadata for each path.

Options

middleware.metadata(router)

This is the function you call to create the metadata middleware.

API

req.swagger

A swagger property is added to the Request object. It’s an object with the following properties:

Property Type Description
api Swagger Object The complete Swagger API object. If the Swagger API has a basePath and the current request is not within that path, then this property is null.
pathName string The Swagger path that corresponds to the current HTTP request. If the current request does not match any paths in the Swagger API, then this property is an empty string.

For example, the “/pets/{petName}/photos/{id}” Swagger path would match a request to “/pets/Fido/photos/123”.
path Path Object The Swagger path object that corresponds to the current HTTP request, or null if the request does not match any path in the Swagger API.
operation Operation Object The Swagger operation object that corresponds to the current HTTP request, or null if the request does not match any operation in the Swagger API.
params array of Parameter Objects The Swagger parameter objects that correspond to the current HTTP request. The array is empty if there are no parameters. These are just the parameter definitions from the API, not the values for the current request. See the Parse Request middleware for parameter values.
security array of Security Requirement Objects The security requirement objects that correspond to the current HTTP request. The array is empty if there are no security requirements. These are just the security definitions from the API, not any validated or authenticated values. See the Validate Request middleware for security validation.