SHARE THIS ARTICLE

Swagger Server Configuration Extensions

Swagger 2.0 facilitates third-party vendors to implement tool specific extensions. These extensions allow customizing behaviors beyond simple API descriptions. We have enabled a similar category of extensions that help you customize APIMATIC code generation engine as per your requirements. The current documentation targets the extensions available for you to specify server configuration information. You can view details on other available APIMATIC extensions for Swagger at:

1) Swagger CodeGen Extensions

2) Swagger TestCase Extensions

APIMATIC also provides a similar extension for API Blueprint whose details can be viewed at API Blueprint Extensions. All the mentioned extensions are supported by both the Import API operation, as well as by our Code Generation as a Service API.

Server Configuration

Server configurations can be used to create multiple environments, multiple servers that can be used with specific endpoints and server URLs with template paramters. You can view more details on this at Server Configuration.

Swagger Extensions for Specifying Server Configuration

APIMATIC offers you swagger extensions that you can use to specify server configuration information within your swagger API description file. When you import this file, we will extract server configuration information from this extension. The alternate way to specify this information is by using the APIMATIC editor once you have imported your API description file.

Server Configuration Extension

This extension must be used within the “info” object by using the property x-server-configuration. Details about this object can be viewed at Swagger Info Object.

{
   "swagger": 2.0,
   "info": {
      ...,
        "x-server-configuration": {
            ...
        }
    },
    ...
}

The fields available are:

NameTypeDetails
default-environmentStringEnvironment to be used by default
default-serverStringServer to be used by default
environments[Environment Object]List of environments available
parameters[Parameter Object]List of template parameters

Server Configuration Object

Example
{
   "x-server-configuration": {
      "default-environment": "production",
      "default-server": "default",
      "environments": [
         {
            "name": "production",
            "servers": [
               {
                  "name": "default",
                  "url": "http://example.com/{templateParam}"
               }
            ]
         }
      ],
      "parameters": [
         {
            "name": "templateParam",
            "description": "It is a template parameter",
            "type": "string",
            "enum": [
               "abc",
               "def",
               "ghi"
            ]
         }
      ]
   }
}

Environment Object

The environment object is used to define a single environment. An environment consists of a set of servers with base URL values. The fields available in this object are:

NameTypeDetails
nameStringName of the environment
descriptionStringDetails about the environment
servers[Server Object]A list of servers in a particular environment
Example
{
   "name": "production",
   "description": "Production environment",
   "servers": [
      {
         "name": "default",
         "url": "http://example.com/{templateParam}"
      }
   ]
}

Server Object

The user can specify multiple servers within an environment. A server comprises of a name and a url. The fields available in this object are:

NameTypeDetails
nameStringName of the server
urlStringBase URL for the server
Example
{
   "name": "default",
   "url": "http://example.com/{templateParam}"
}

Parameter Object

Parameter Object helps define the template parameters that can be used inside URLs. These parameters are defined using the Parameter Object with rules that apply for parameters in template.

Example
{
   "name": "templateParam",
   "description": "It is a template parameter",
   "type": "string",
   "enum": [
      "abc",
      "def",
      "ghi"
   ]
}

Parameter Type   The parameter can only be of the following types: string, number, number enum, string enum

Endpoint Server Name Extension

The base URL for a specific endpoint can be overriden by using the server name extension in the Operation Object. The extension consists of the following single field:

NameTypeDetails
x-server-nameStringName of the server

Example

{
   "get": {
      "description": "Get operation",
      "x-server-name": "default",
      "tags": [
         "Examples"
      ],
      "operationId": "Example",
      "produces": [
         "application/json"
      ],
      "parameters": [],
      "responses": {
         "200": {
            "description": ""
         }
      }
   }
}

Conclusion

In this way you can specify server configuration in your Swagger file using our APIMATIC extensions. You will then not be required to manually add this information through the editor everytime you import your Swagger file.


Have questions? Submit a request.