OpenAPI Server Configuration Extensions

OpenAPI/Swagger (v2.0, v3.x) facilitates third-party vendors to implement tool specific extensions. These extensions allow customizing behaviors beyond simple API definitions. 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 OpenAPI at:

1) OpenAPI CodeGen Extensions

2) OpenAPI 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 parameters. You can view more details on this at Server Configuration.

OpenAPI Extensions for Specifying Server Configuration

APIMatic offers you OpenAPI vendor extensions that you can use to specify server configuration information within your OpenAPI/Swagger API definition 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 definition 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 Info Object v2, v3.

{
   "openapi": "3.0.0",
   "info": {
      ...,
        "x-server-configuration": {
            ...
        }
    },
    ...
}

The fields available are:

Name	Type	Details
default-environment	String	Environment to be used by default
default-server	String	Server 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",
            "schema": {
               "type": "string",
               "enum": [
                  "abc",
                  "def",
                  "ghi"
               ],
               "default": "abc"
            }
         }
      ]
   }
}

OpenAPI 3.x Root Servers

The Server Configuration extension will override any information specified in the servers property of the OpenAPI 3.x root object.

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:

Name	Type	Details
name	String	Name of the environment
description	String	Details 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:

Name	Type	Details
name	String	Name of the server
url	String	Base 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 v2, v3 with rules that apply for parameters in template. In addition to those, you must also specify a default value for the parameter using the default property.

Example

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

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 overridden by using the server name extension in the Operation Object v2, v3. The extension consists of the following single field:

Name	Type	Details
x-server-name	String	Name 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 OpenAPI file using our APIMatic extensions. You will then not be required to manually add this information through the editor every time you import your OpenAPI file.