Swagger 2.0 Extension for Code Generation Settings

Swagger 2.0 spec was created with the foresight of allowing 3rd-party vendors to implement tool-specific extensions. These extensions allow customizing behaviors beyond simple API descriptions. Traditionally, such behaviors used to stay locked inside custom settings, restricting the interoperability of tools and services. Using these extensions, we can not only offer extended compatibility between tools and services, but this also opens up a pathway to improve and add missing features that eventually become de-facto standard for API descriptions. For example, extensions that allow customization of API analytics data collections e.g., how to treat rate limit exceeded, may eventually become part of official Swagger spec if the developer community decide in its favor. One widely known example of Swagger vendor extension is the Apigee a-127 extension, which allows you to generate APIs in Node.js. API Evangelist has already written a post about this concept some while ago (read it here).

APIMatic CodeGen Extensions

APIMATIC’s code generation engine is highly customizable. You can decide on naming convention, configuration stores, and perform some white labelling through our CodeGen Settings, and Advanced Settings per Endpoint. However, this customizability was previously locked behind our API Editor UI, and inside our internal API format (called APIMATIC format). We were often asked how to specify these settings from other API description formats, specially Swagger. So, we are now announcing our vendor extensions for Swagger 2.0, which can be used to specify the said settings for complete customizability. The extensions are supported by both the “Import” API operation, as well as by our Code Generation as a Service API (read more here).

CodeGen Settings for Swagger 2.0

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,
  “iOSGenerateCoreData”: false,
  “androidUseAppManifest”: true,
  “collectParameters”: false,
  “csharpDefaultNamespace”: “ACME.CORP.API”,
  “javaDefaultPackageName”: “com.acme.corp.api”,
  “appendContentHeaders”: true,
  “brandLabel”: “ACME Corp.”,
  “userAgent”: “APIMATIC 2.0”,
  “enableAdditionalModelProperties”: false
  }
 },
 …
}

The purpose of these parameters is explained below.

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.

iOSGenerateCoreData

When true, iOS CoreData schema and classes are generated.

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.

csharpDefaultNamespace

A valid C# namespace value to be used as the default namespace. Leave empty or null to automatically generate.

javaDefaultPackageName

A valid Java package name to be used as the base package name. Leave empty or null to automatically generate. This value is applied for both Java and Android code generation templates.

appendContentHeaders

When true, code generation engine automatically detects request and response schema and appends content headers e.g., “accept: application/json” and “content-type: application/json” headers for JSON serialization mode.

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.

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 a “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”
 },
 …
 ]
 }
}

Please direct any queries on this aspect to our support team.