API Documentation with OpenAPI | Noroff Front-end Development

Proper documentation helps other developers understand how to use your endpoints when building APIS. You’ve used OpenAPI documentation when working with the Noroff APIs; now, we’ll see how to add it to the APIs you build.

This documentation isn’t just a static reference - it’s interactive, allowing developers to test endpoints directly from the documentation interface.

Setting Up OpenAPI Documentation

OpenAPI is the industry standard for documenting REST APIs. Install the required packages:

npm install swagger-ui-express swagger-jsdoc
npm install --save-dev @types/swagger-ui-express @types/swagger-jsdoc

Configuring Swagger UI

Update your index.ts file with the new Swagger setup:

// Other imports
import swaggerUi from "swagger-ui-express";
import swaggerJSDoc from "swagger-jsdoc";

const app = express();
const PORT = process.env.PORT || 3000;

// Swagger configuration
const swaggerOptions = {
  definition: {
    openapi: "3.0.0",
    info: {
      title: "Dev platforms API",
      version: "1.0.0",
      description: "A simple API for managing users and posts",
    },
    servers: [{ url: `http://localhost:${PORT}` }],
  },
  apis: ["./src/routes/*.ts"],
};

const swaggerSpec = swaggerJSDoc(swaggerOptions);

app.use(express.json());

// API documentation endpoint
app.use("/api-docs", swaggerUi.serve, swaggerUi.setup(swaggerSpec));

// Existing route modules
app.use("/users", userRoutes);
app.use("/posts", postRoutes);

Understanding the new code

Import packages: We import swagger-ui-express for the web interface and swagger-jsdoc to process documentation comments.
swaggerOptions object: Contains the basic API information (title, version, description) and configuration.
swaggerOptions.apis property: This array tells Swagger which files to scan for documentation comments - "./src/routes/*.ts" means all TypeScript files in the routes folder.
swaggerSpec: The swaggerJsdoc() function combines the configuration with route comments to generate the API documentation.
Documentation route: app.use("/api-docs", ...) creates an endpoint that serves the interactive Swagger UI interface.
Testing: Visit http://localhost:3000/api-docs after starting the server to see the interactive documentation. You will see a message saying, “No operations defined in spec,” as we have yet to document any routes.

Documenting Your Routes

We need to add special comments on each route that describe what the endpoint does, what parameters it expects, and what responses it returns.

These comments use JSDoc syntax with @swagger tags, and the information you write here will appear in the interactive documentation interface. Here are two examples in routes/users.ts - you can add similar documentation to all your other routes:

/**
 * @swagger
 * /users:
 *   get:
 *     summary: Get all users
 *     responses:
 *       200:
 *         description: List of users
 */
router.get("/", async (req, res) => {
  // code
});

/**
 * @swagger
 * /users/{id}:
 *   get:
 *     summary: Get user by ID
 *     parameters:
 *       - in: path
 *         name: id
 *         required: true
 *         schema:
 *           type: integer
 *     responses:
 *       200:
 *         description: User details
 *       400:
 *         description: Invalid user ID
 *       404:
 *         description: User not found
 */
router.get("/:id", validateUserId, async (req, res) => {
  // code
});

Now refresh http://localhost:3000/api-docs to see the interactive API documentation. You’ll see that the endpoints that have documentation comments are listed with their details.

To test an endpoint:

Click the down arrow to expand the route details.
Click the “Try it out” button.
Fill in any required parameters or request body data.
Click the “Execute” button to send the request.

This interactive documentation can replace tools like Postman for testing your API endpoints, making it easy for other developers to understand and test your API.

Repo link

Tags: