Swagger Express Middleware

Swagger 2.0 middlware and mocks for Express.js

API Dev Tools View project on GitHub

Sample 1 Walkthrough

JavaScript Walkthrough

Now that you have the sample running, it’s time to look at the source code. Open up sample1.js and let’s see what it’s doing.

Creating an Express Application

If you’re already familiar with Express.js, then the first few lines should be pretty familiar. We require('express') and then create a new Express Application. If this is new to you, then you might want to take some time to read the Getting Started guide on the Express website.

Middleware initialization

The next few lines of code are where we really start working with Swagger Express Middleware. First we use path.join() to get the full path of our Swagger file, then we use it to initialize the middleware. For more details about this line, see the createMiddleware function documentation.

createMiddleware(swaggerFile, app, function(err, middleware) {

Middleware initialization happens asynchronously. During this time, it parses and validates the Swagger file and reads/downloads any other files that are referenced by $ref pointers. When this process is complete, the callback function will be called. If there was an error during the initialization and parsing process, then the err parameter will be set; otherwise, it will be null. But either way, the middleware parameter will be initialized and you can now add Swagger middleware to your Express Application.

// Add all the Swagger Express Middleware, or just the ones you need.
// NOTE: Some of these accept optional options (omitted here for brevity)
app.use(
    middleware.metadata(),
    middleware.CORS(),
    middleware.files(),
    middleware.parseRequest(),
    middleware.validateRequest(),
    middleware.mock()
);

As the comment says, you don’t have to add all of the Swagger middleware modules to your app. You can choose just the ones you need, but you’ll need to check the documentation because some of the middleware modules require other modules. Also, many of the middleware modules have optional settings that you can use to customize their behavior. Those are also covered in the documentation.

Starting the server

The next block of code is pretty standard for any Express app. The listen method tells the server start listeing for requests on port 8000. The callback function is called once the port has been opened and is ready to begin accepting requests.

app.listen(8000, function() {

Sample 1 Walkthrough