Swagger 2.0 Extension for Code Generation Settings – APIMATIC - Support

This article is now deprecated. Please click here to see the new docs.

Vendor extensions for Swagger 2.0, allow you customise code generation settings such as naming convention, configuration stores, and perform some white labelling, and Advanced Settings per Endpoint. The extensions are supported for both "Import" operation, as well as by our Code Generation as a Service API (read more here).

We discuss below the various vendor extensions available for Swagger 2.0.

CodeGen Settings:

We followed the Swagger 2.0 extensions spec and created a new property definition inside the "info" object, named "x-codegen-settings". These settings are globally applicable to all operations and schema definitions. See example below.

{
    "swagger": 2.0,
    "info": {
        ...,
        "x-codegen-settings": {
            "generateAsyncCode": true,
            "useMethodPrefix": true,
            "useModelPostfix": true,
            "useControllerPostfix": true,
            "useEnumPostfix": true,
            "useConstructorsForConfig": true,
            "iOSUseAppInfoPlist": true,
            "androidUseAppManifest": true,
            "collectParameters": false,
            "brandLabel": "YOUR COMPANY NAME",
            "userAgent" : "APIMATIC 2.0",
            "enableAdditionalModelProperties" : false
        }
    },
    ...
}

The purpose of these parameters is explained below.

Parameter	Purpose
generateAsyncCode	When true, the CodeGen engine generates asynchronous C# and Java code.
useMethodPrefix	When true, HTTP verbs are used as prefix for generated controller methods.
useModelPostfix	When true, a postfix "Model" is appended to all classes generated from schemas.
useControllerPostfix	When true, a postfix "Controller" is appended to all controllers generated from path groups.
useEnumPostfix	When true, a postfix "Enum" is appended to all enumerations lifted from "allowedValues".
useConstructorsForConfig	When true, configuration values e.g., authentication credentials, are accepted as controller constructor parameters. Otherwise, these values generate variables in a Configuration class.
iOSUseAppInfoPlist	When true, configuration values e.g., authentication credentials, are expected in app-info.plist file for the iOS SDK. When set, this setting ignores useConstructorsForConfig flag.
androidUseAppManifest	When true, configuration values e.g., authentication credentials, are expected in AndroidManifest.xml file for the Android SDK. When set, this setting ignores useConstructorsForConfig flag.
collectParameters	When true, operation parameters are expected to passed as a collection. For example in PHP, the generated method expects a Map containing parameters as Key-Value pairs. This is currently implemented for PHP, Python, GO, and Objective-C. When set, this is applied globally on all endpoints/operations. If you wish to use this option on specific endpoints, use the x-operation-settings::collectParameters instead.
brandLabel	A string value to brand the generated files. For example: "Acme Corp."
userAgent	A string value to use as user-agent in the API calls. This is useful for analytics and tracking purposes. For example: "SDK V1.1"
enableAdditionalModelProperties	When true, additional or unknown properties in the response JSON are collected into a dictionary.

Advanced Settings:

APIMATIC allows further customization of endpoints (called operations in Swagger). These settings can be specified inside an "operation" object using property name "x-operation-settings". See an example as following.

"paths": {
    "/pets": {
        "get": {
            ...,
            "x-operation-settings" : {
                "collectParameters" : false,
                "allowDynamicQueryParameters": true,
                "allowDynamicFormParameters": false,
                "isMultiContentStreaming": false
            }
        }
    }
}

The purpose of these parameters is explained below.

Parameter	Purpose
collectParameters	When true, this operation's parameters are expected to passed as a collection. For example in PHP, the generated method expects a Map containing parameters as Key-Value pairs. This is currently implemented for PHP, Python, GO, and Objective-C.
useModelPostfix	When true, a postfix "Model" is appended to all classes generated from schemas.
allowDynamicQueryParameters	When true, the generated method has an additional Map input, which may contain dynamic number of query parameters as Key-Value pairs.
allowDynamicFormParameters	When true, the generated method has an additional Map input, which may contain dynamic number of form parameters as Key-Value pairs.
isMultiContentStreaming	When true, it indicates that this operation is a streaming endpoints. For example Twitter Streaming API endpoints.

Additional Headers:

APIMATIC allows defining global headers that are sent with every API call. These headers are in addition to any headers required for authentication or defined as parameters. These headers can be specified inside an "Security Scheme" object using property name "x-additional-headers". See an example below.

"securityDefinitions": {
    "basicAuth": {
        "type": "basic",
        "x-additional-headers": [
            {
                "name": "API Version",
                "description": "The version number indicator for the API",
                "default": "1.1"
            },
            {
                "name": "SDK Version",
                "description": "The version number indicator for the SDK",
                "default": "1.1.0.1"
            },
            ...
        ]
    }
}