OpenAPI Spec: Basic Info & Servers in JSDoc

1. The Role of info and servers

Before we modify the code, let's be crystal clear on what these two objects do.

• info: This object is the business card of your API. It holds the essential metadata:
  • title: The name of your API.
  • version: The current version of your API. This is critical for version management.
  • description: A brief explanation of what your API does.
• servers: This is an array that lists the base URLs where your API can be accessed. This is incredibly useful because it allows anyone using your documentation (including an examiner) to switch between different environments, like your local machine and the live production server, with a single click.

The configuration you write directly generates the header section of your interactive documentation page, as shown below.

2. Professionalizing Configuration with Environment Variables

In the previous lesson, we hardcoded the title and description directly into the swaggerOptions object. This is fine for a quick start, but a much better practice is to manage this information as part of your environment configuration. It centralizes your project's key settings and makes them easy to change without digging through code.

This pattern is a common professional standard and is demonstrated well in the following article.

3. Action: Move API Metadata to .env

Let's apply this pattern to your project.

1. Update your .env file:
   Open your .env file and add the following variables. Feel free to customize the values.

   
   
   
   # .env
   
   
   
   
   # ... your existing MONGO_URI and PORT
   
   
   
   
   # Swagger API Info
   API_TITLE=CRUD API for Certification
   API_VERSION=1.0.0
   API_DESCRIPTION=A RESTful API for managing items, built for the backend certification exam.
   

2. Update your Swagger Configuration:
   Now, open your main server file (e.g., src/server.js) and modify the info object within swaggerOptions to read from process.env.

   // src/server.js
   
   // ... other code
   
   const swaggerOptions = {
     definition: {
       openapi: '3.0.0',
       info: {
         title: process.env.API_TITLE, // Use environment variable
         version: process.env.API_VERSION, // Use environment variable
         description: process.env.API_DESCRIPTION, // Use environment variable
       },
       // ... servers and components will be here
     },
     apis: ['./src/routes/*.js'],
   };
   
   // ... rest of the file
   

This change makes your documentation's metadata easily configurable and separates it from your application logic.

4. Configuring for Development and Production Servers

Your API will exist in at least two places: on your local machine (localhost) for development, and on a live server (like Render or Railway) for production. Your documentation should reflect this.

The servers property is an array, meaning you can list multiple server URLs. Let's configure it for both environments. We'll use a placeholder for the production URL for now, which you will replace with your actual live URL during the deployment lesson.

// Inside your swaggerOptions.definition object

servers: [
  {
    url: `http://localhost:${process.env.PORT || 5001}`,
    description: 'Development server',
  },
  {
    url: 'https://your-app-name.onrender.com', // << REPLACE THIS during deployment
    description: 'Production server',
  },
],

5. Finalizing Your Base Configuration

Let's put everything together. Your complete swaggerOptions object should now look like this. Make sure it is placed in your main server file (src/server.js or app.js) before your routes and error handlers.

Action: Verify Your Final Configuration

Replace your existing swaggerOptions with the code below to ensure everything is correct.

// src/server.js or app.js

// ... other imports
const swaggerUi = require('swagger-ui-express');
const swaggerJSDoc = require('swagger-jsdoc');
// ...

const app = express();
// ...

// --- Swagger Configuration ---
const swaggerOptions = {
  definition: {
    openapi: '3.0.0',
    info: {
      title: process.env.API_TITLE,
      version: process.env.API_VERSION,
      description: process.env.API_DESCRIPTION,
    },
    servers: [
      {
        url: `http://localhost:${process.env.PORT || 5001}`,
        description: 'Development server',
      },
      {
        url: 'https://your-app-name.onrender.com', // Placeholder for production
        description: 'Production server',
      },
    ],
    // The components/schemas part you added in the last lesson goes here
    components: {
        /* Your schemas from previous lesson */
    }
  },
  apis: ['./src/routes/*.js'], // Path to the files containing API definitions
};

const swaggerSpec = swaggerJSDoc(swaggerOptions);

// --- Serve Swagger Docs ---
// This should be placed *before* your API routes
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerSpec));

// ... your API routes, 404 handler, and error handler

Now, restart your server (npm run dev) and refresh the http://localhost:5001/api-docs page in your browser. You should see:

1. The title, version, and description now reflect the values from your .env file.
2. A new "Servers" dropdown menu is visible, allowing you to select between your "Development server" and the "Production server" placeholder.

Conclusion

You have now successfully defined a professional and configurable base for your API documentation. This attention to detail is exactly what examiners look for, as it demonstrates an understanding of how real-world applications are managed.

Key Takeaways:

• The info and servers objects are the foundation of your OpenAPI specification, providing essential metadata and API locations.
• Storing metadata like title and version in .env files is a best practice that separates configuration from code.
• Defining multiple server URLs makes your documentation immediately useful for different environments and is a required step for preparing your project for deployment.

Next Up:

With the base specification fully configured and served at the /api-docs endpoint, you are ready to document your actual API operations. In the next lesson, you will write the documentation for all your CRUD endpoints, bringing your interactive API documentation to life.