Swagger 2.0 Extension for Code Generation Settings

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"
            },
            ...
        ]
    }
}
Have more questions? Submit a request

Comments