OpenAPI, OPA & Swagger-JSDoc

4. Advantages of the Approach

• Consistency and Accuracy: The swagger-jsdoc approach tightly couples documentation to the code, making it far more reliable than manually maintained documentation.

• Centralized Policy Management: OPA allows for a single, centralized policy repository, which is essential for enforcing consistent security rules across a large number of microservices.

• Flexibility and Expressiveness: OPA's Rego language is highly expressive and can handle complex, attribute-based access control (ABAC) rules that would be difficult to implement and maintain in traditional imperative code.

• Reduced Development Overhead: Developers don't need to write repetitive authorization checks in every route handler. They can offload that responsibility to OPA.

5. A Practical Example: A Simple Express.js API

Let's illustrate this with a simple Express.js API that uses swagger-jsdoc for documentation and OPA for a user management endpoint.

api.js (Express.js server):

const express = require('express');

const app = express();

const swaggerJsdoc = require('swagger-jsdoc');

const swaggerUi = require('swagger-ui-express');

const axios = require('axios'); // For communicating with OPA

const port = 3000;

app.use(express.json());

// Swagger JSDoc options

const swaggerOptions = {

  definition: {

    openapi: '3.0.0',

    info: {

      title: 'User Management API',

      version: '1.0.0',

      description: 'A simple API to manage user data with authorization via OPA.',

    },

    servers: [{ url: `http://localhost:${port}` }],

    components: {

      securitySchemes: {

        bearerAuth: {

          type: 'http',

          scheme: 'bearer',

          bearerFormat: 'JWT',

        },

      },

    },

    security: [{ bearerAuth: [] }],

  },

  apis: ['./api.js'], // Point to the file with JSDoc comments

};

const swaggerSpec = swaggerJsdoc(swaggerOptions);

app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerSpec));

// Middleware to check authorization with OPA

const authorize = async (req, res, next) => {

  const opaUrl = 'http://localhost:8181/v1/data/httpapi/authz';

  // Construct the OPA input payload

  const input = {

    method: req.method,

    path: req.path.split('/').filter(p => p),

    user: req.headers['x-user-id'], // Example user identifier

  };

  try {

    const { data } = await axios.post(opaUrl, { input });

    if (data.result.allow) {

      next(); // User is authorized, proceed

    } else {

      res.status(403).json({ error: 'Forbidden' });

    }

  } catch (error) {

    console.error('OPA communication error:', error.message);

    res.status(500).json({ error: 'Internal Server Error' });

  }

};

// --- API Endpoints ---

/**

 * @swagger

 * /users:

 * get:

 * summary: Retrieve a list of users.

 * description: This endpoint requires authorization.

 * responses:

 * 200:

 * description: A list of users.

 * content:

 * application/json:

 * schema:

 * type: array

 * items:

 * type: object

 * properties:

 * id:

 * type: integer

 * name:

 * type: string

 * 403:

 * description: Forbidden, user is not authorized.

 */

app.get('/users', authorize, (req, res) => {

  const users = [{ id: 1, name: 'Alice' }, { id: 2, name: 'Bob' }];

  res.json(users);

});

app.listen(port, () => {

  console.log(`Server running on http://localhost:${port}`);

  console.log(`API documentation available at http://localhost:${port}/api-docs`);

});

policy.rego (OPA policy):

package httpapi.authz

// By default, all requests are denied.

default allow = false

// Allow access to the '/users' endpoint if the user ID is 'admin'.

allow if {

    input.method == "GET"

    input.path == ["users"]

    input.user == "admin"

}

Running the Example:

1. Start OPA: Run OPA in server mode with the policy file.  opa run --server --set decision_logs.console=true policy.rego

2. Start the Express.js Server: node api.js

3. Test:

   • Navigate to http://localhost:3000/api-docs to see the generated Swagger UI.

   • Make a GET request to http://localhost:3000/users with a x-user-id header of admin. The request will be allowed.

   • Make the same request with any other user ID. The request will be denied with a 403 Forbidden error, and the OPA logs will show the decision.