Forum Discussion

btalebpour's avatar
btalebpour
Occasional Contributor
2 years ago

Dynamic/Variable servers URLs in the swagger document

I was trying to find out how I could specify my server URLs inside my swagger.json file so that when we deploy the documentation to the different servers (i.e., production, staging, dev, etc), each link points to the right server without user involvement. Currently, I have the following setup which works fine:

 

"servers": [
      {
         "url": "https://.../api/.../v1",
         "description": "Staging server"
      },
      {
         "url": "https://.../api/.../v1",
         "description": "Production server"
      }
]
 
I am looking to do something like this:
   "servers": [
      {
         "url": process.env.serverUrl,
         "description": process.env.serverName
      }
]
 
I am using swagger-ui-express in a Vue CLI project.
  • To include dynamic or variable server URLs in a Swagger document, you can make use of server variables. Server variables allow you to define placeholders in the server URLs that can be replaced with actual values during runtime. Here's how you can do it:

    1. Open your Swagger document (usually a YAML or JSON file) in an editor of your choice.

    2. Locate the servers section in your Swagger document. If it doesn't exist, you can add it at the root level or within a specific API definition.

    3. Inside the servers section, define a server object with the url property. This will serve as the base URL for your API.

    4. Use curly braces {} to enclose the variable placeholders within the url. For example, {variable}.

    5. Below the url property, define a variables object. This object will hold the mapping of the variable name to its values.

    6. Inside the variables object, define each variable name as a property and specify its possible values using the enum property.

    7. Save the Swagger document after making the necessary changes.

    With this setup, you can provide different values for the server variables during runtime, allowing you to switch between different server URLs easily. The values for the server variables can be provided either through configuration files, environment variables, or programmatically, depending on the tool or framework you are using to serve your API.

    Note that the implementation of server variables may vary depending on the specific Swagger tool or framework you are using. It's recommended to refer to the documentation or guides provided by the tool or framework you're working with for detailed instructions on how to define and use server variables in Swagger documents.

     

     

    pickleball paddle cover

  • nehakakar's avatar
    nehakakar
    Occasional Contributor

    You can use a combination of environment variables and server-side code to generate the swagger.json file dynamically during deployment.

    This way, the server URLs will be automatically set based on the environment where the application is deployed 

    Here are the steps.....

    Set up environment variables for each of your server URLs. 

    During the build or deployment process, use server-side code or a build script to generate the swagger.json file dynamically.

    In your case, since you're using Vue CLI, you can use a build script to perform this task.

    Within the build script, read the environment variables you defined in Step 1 and inject them into the swagger.json file.

    Replace the placeholders for server URL and server name with the actual values from the environment variables.

    Once the swagger.json file is generated with the correct server URLs, serve it to your Swagger UI or Swagger Express middleware.

     

    Here's an example of how i did with Node.js and Vue CLI

    1. Create a swagger-config.js file in the root of your project.

     

    javascript
    const fs = require('fs');
    const { serverUrl, serverName } = process.env;
    
    const swaggerJson = {
      openapi: '3.0.0',
      // ... other parts of your swagger.json ...
      servers: [
        {
          url: serverUrl,
          description: serverName,
        },
      ],
      // ... other parts of your swagger.json ...
    };
    
    fs.writeFileSync('dist/swagger.json', JSON.stringify(swaggerJson));

     

    2. In your package.json, update the build script to execute the swagger-config.js before the build:

     

    json
    {
      "scripts": {
        "build": "node swagger-config.js && vue-cli-service build"
      }
    }

     

    Before deploying your application, set the environment variables for each environment ex... production, staging, dev..

    Now Run the build command to generate the dynamic swagger.json:

     

    bash
    npm run build

     

    Deploy the contents of the `dist` folder, which should now include the dynamic swagger.json with the correct server URLs.

    Hopefully, your Swagger document will automatically have the correct server URLs based on the environment where it is deployed,