APIMatic November 7, 2015

API Blueprint Extension for Code Generation Settings

We have just launched Code Generation Extensions for API Blueprint. These extensions allow customizing the behaviour of APIMatic’s Code Generation Engine. By specifying additional metadata in your API Blueprint description, you can now control the naming conventions, configuration stores and have your custom code branding. We refer to these as Code Generation Settings. Previously, you had to import your API Blueprint into APIMATIC format and use our Editor UI to specify these settings. Some while ago we made a similar extension available for Swagger 2.0 (read more here). But if your API description uses API Blueprint, you can leverage this as well.

API Blueprint CodeGen Settings

We extended the API Blueprint metadata attribute to specify additional properties. See the following example below:

FORMAT: 1A

HOST: http://api.datumbox.com/GENERATEASYNCCODE: TRUE
USEMETHODPREFIX: TRUE
USEMODELPOSTFIX: TRUE
USECONTROLLERPOSTFIX: TRUE
USEENUMPOSTFIX: TRUE
USECONSTRUCTORSFORCONFIG: TRUE
IOSUSEAPPINFOPLIST: TRUE
IOSGENERATECOREDATA: FALSE
ANDROIDUSEAPPMANIFEST: TRUE
COLLECTPARAMETERS: FALSE
CSHARPDEFAULTNAMESPACE: ACME.CORP.API
JAVADEFAULTNAMESPACE: 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.

JAVADEFAULTNAMESPACE

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.

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