Overview

Skill Level: Intermediate

Create an API using Node.js and ExpressJS that automatically validates API requests against an OpenAPI 3 spec.

Ingredients

We'll build the API server using Node.js and Express. We’ll utilize express-openapi-validator to automatically validate API requests using an OpenAPI 3 specification.

To complete this recipe, we'll use:

Step-by-step

  1. Create an Express application for our simple API

    First let’s create a simple Express application.

     

    Running the above code launches an API server that exposes the following routes:

    • GET /v1/pets
    • POST /v1/pets
    • GET /v1/pets/:id

    Note: The APIs return values are contrived and not relevant to this tutorial.

  2. Create an OpenAPI spec to describe our API

    Now that we have written our simple API, let’s add some validation. BUT, instead of writing a bunch of validation code, we’ll describe our API by creating an OpenAPI 3 specification.

    (I’ll assume you know how to create an OpenApi spec, hence I’ll describe only the relevant snippets. If you’d like to see the full spec, go here).

    Let’s make it a requirement that requests to GET /v1/pets must provide the query parameter, limit. Let’s also require that limit be an integer with a value greater than zero.

    Let’s also make it a requirement that requests to POST /v1/pets must provide a JSON body containing a required field, name.

     

    We’ll also add the NewPets component to our OpenAPI 3 spec.

  3. Integrate automatic request validation with Express-OpenAPI-Validator

    Finally, we’ll make a few minor code adjustments to enable our API server to automatically validate API requests using our OpenAPI 3 specification.

    The code adjustments include the following:

    Require express-openapi-validator — a package to automatically validate routes defined in Express against an OpenAPI 3 spec

    1. Install the OpenApiValidator onto our express application
    2. Provide an Express error handler to customize our error responses
    3. After making these changes, our final code is as follows:

    (Note, steps 1, 2, and 3 indicating the new code that’s been added)

    Start the server, then…

  4. Try it out

    Let’s execute some API requests with curl and observe the automatic request validation in action.

    Let’s try GET /v1/pets

    Returns

    Let’s try POST /v1/pets

    Returns

    The full source code for this example can be found here.

    If you dig express-openapi-validator,

    Star it on Github!

Join The Discussion