Metadata
You can now import/convert your API description along with a metadata file that will allow you to configure Code Generation Settings for your API, override authentication settings or control parsing of some components. Details on how to provide this file and its format are provided below.
Applicability
You can provide this file along with your API description during import on the My APIs page or when converting APIs on the Transformer.
Metadata File
The metadata file must be a valid JSON file and the file name MUST start with “APIMATIC-META”.
How to Provide the Metadata File
The API description must be provided in the form of a ZIP file that contains both the API description and this metadata file. Within the ZIP file, the metadata file must exist at the same level as that of the API description. It should not be nested at a different level.
Advantages
When importing an API through the My APIs page, this file enables you to configure Code Generation settings for your API. This is useful when you are importing from a format other than APIMATIC that do not have support for specifying additional parameters useful only to SDK generation in APIMATIC.
You can override the default authentication settings of your API with those specified in the file.
Helps you import various components of an API description file in accordance with any rules specified in the settings.
File Format
The metafile can consist of various JSON objects that will help specify this information. These objects are described in the sections below.
Authentication
The details on the authentication options available in APIMATIC are described here API Authentication. To enable these options via the metafile, you need to specify the authentication object that has the following properties:
Authentication Object
Name: Authentication
Property | Type | Details |
---|---|---|
Type | String | MUST be a value from one of [None,Basic, OAuth_v2_BearerToken, CustomQuery,CustomHeader, OAuth_v1_TokenSecret, CustomAuth, JWT, OAuth_v1_Cert_PKCS12_RSA, OAuth_v1a_OneLeggedFlow] |
Parameters | [Parameter Object] | Array of type Parameter Object |
Example:
{
"Authentication": {
"Type": "Basic",
"Parameters": [
{
"Name": "username",
"Description": "your username"
},
{
"Name": "key",
"Description": "your api key"
}
]
}
}
Parameter Object
Property | Type | Details |
---|---|---|
Name | String | Name of the authentication parameter |
Description | String | Details of the authentication parameter |
DefaultValue | String | Any default value for the authentication parameter |
Example:
{
"Name": "apikey",
"Description": "An API key is required for authentication"
}
Code Generation Settings
The details on the available code generation settings is available at Code Generation Settings . These can be specified in the form of an object as described below:
Code Generation Object
Name : CodeGenSettings
The available properties and their respective types are as follows:
Setting | Type | Purpose |
---|---|---|
SynchronyMode | Number. Could be 0 or 1. | 0 represents Asynchronous while 1 represents Synchronous. When Asynchronous, the CodeGen engine generates asynchronous C# and Java code. |
ArraySerialization | String | Array serialisation scheme for primitive types (applicable to form and query params). Allowed values are Indexed , UnIndexed , Plain , CSV , TSV , PSV |
UseHttpMethodPrefix | Boolean | When true, HTTP verbs are used as prefix for generated controller methods. |
UseModelPrefix | Boolean | When true, a postfix “Model” is appended to all classes generated from schemas. |
UseEnumPrefix | Boolean | When true, a postfix “Enum” is appended to all enumerations lifted from “allowedValues”. |
AppendContentHeaders | Boolean | 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. |
UseCommonSDKLibrary | Boolean | When true, a common library comprising of common classes is used by the generated SDKs |
UseControllerPrefix | Boolean | When true, a postfix “Controller” is appended to all controllers generated from path groups. |
GenerateInterfaces | Boolean | When true, interfaces for controller classes are generated in the generated SDKs |
PreserveParameterOrder | Boolean | When true, parameter order is tried to be preserved in endpoints and models |
AndroidUseAppManifest | Boolean | 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. |
EnablePHPComposerVersionString | Boolean | When true, adds version component to composer.json file in PHP SDKs. This can cause conflicts with Git tag-based version publishing and should be used with care. |
iOSUseAppInfoPlist | Boolean | 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 | Boolean | When true, iOS CoreData schema and classes are generated. |
CollapseParamsToArray | Boolean | When true, collapse more than 3 parameters into an options arrays |
Nullify404 | Boolean | When true, null response will be returned on the HTTP status code 404 |
ValidateRequiredParameters | Boolean | When true, required API endpoint parameters are validated to be not null |
PreserveParameterOrder | Boolean | When true, parameter order is tried to be preserved in endpoints and models |
Timeout | Float | When true the requests will timeout after the specified duration |
EnableAdditionalModelProperties | Boolean | When true, additional or unknown properties in the response JSON are collected into a dictionary. |
BrandLabel | String | A string value to brand the generated files. For example: “Acme Corp.” |
UserAgent | String | 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” |
ProjectName | String | The name of the project for the Generated SDKs |
CSharpNamespace | String | A valid C# namespace value to be used as the default namespace. Leave empty or null to automatically generate. |
JavaPackageName | String | 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. |
RunscopeEnabled | Boolean | When true Runscope pass-through for traffic monitoring will be enabled |
RunscopeBucket | String | This is the Runscope Bucket Key for traffic monitoring |
GenerateTravisConfig | Boolean | When true, the Travis Configuration file will be generated along with the SDK |
GenerateCircleConfig | Boolean | When true, the Circle Configuration file will be generated along with the SDK |
GenerateAppveyorConfig | Boolean | When true, the Appveyor Configuration file will be generated along with the SDK |
GenerateJenkinsConfig | Boolean | When true, the Jenkins Configuration file will be generated along with the SDK |
Example:
{
"CodeGenSettings": {
"SynchronyMode": 0,
"ModelSerializationScheme": "Json",
"ArraySerialization": "Indexed",
"Nullify404": true,
"UseHttpMethodPrefix": true,
"UseModelPrefix": true,
"UseExceptionPrefix": true,
"UseEnumPrefix": true,
"UseControllerPrefix": true,
"UseConstructorsForConfig": true,
"Timeout": 0.1,
"AndroidUseAppManifest": true,
"iOSUseAppInfoPlist": true,
"iOSGenerateCoreData": true,
"CollapseParamsToArray": true,
"RunscopeEnabled": true,
"RunscopeBucket": "key",
"AndroidHttpClient": "UNIREST",
"ObjCHttpClient": "UNIREST",
"CSharpHttpClient": "UNIREST",
"CSharpNamespace": "Root",
"JavaPackageName": "Root",
"JavaUsePropertiesConfig": false,
"PHPHttpClient": "UNIREST",
"BrandLabel": "Label",
"UserAgent": "User",
"ProjectName": "Calculator",
"EnableAdditionalModelProperties": true,
"PreserveParameterOrder": true,
"ValidateRequiredParameters": true,
"AppendContentHeaders": true,
"GenerateInterfaces": true,
"UseCommonSDKLibrary": true,
"ParameterArrayFormat": 2,
"GenerateTravisConfig": true,
"GenerateCircleConfig": true,
"GenerateAppveyorConfig": true,
"GenerateJenkinsConfig": true,
"EnableLogging": false,
"EnableHttpCache": false,
"EnablePHPComposerVersionString": false
}
}
Import Settings
These settings allows you to configure the import through various options e.g. settings that lets you override names of components, etc.
Import Settings Object
The available properties and their respective types are as follows:
Setting | Type | Purpose |
---|---|---|
PreferJsonSchemaNameOverTitle | Boolean | By default, this is set to false and if a title is specified in a JSON Schema definition we consider this as the model name. However, when true , we give precedence to the definition name instead of the one specified using property title . |
AppendParentNameForClashes | Boolean | By default, this is set to false and when loading models/complex types, if there is a clash in names we append a number with the name of the clashing type. When true , the name of the parent component is appended with the name instead. Note This is currently supported only for import from |
AutoGenerateTestCases | Boolean | For several formats like OpenAPI (v3.0), API Blueprint, RAML, Postman and HAR, we support auto-generating test cases from request/response examples (if any are present). By default, this will be enabled but can be disabled by setting this flag to false . |
IgnoreRamlTypeDeclarationDisplayName | Boolean | By default, this is set to false . When true , the displayName property for any RAML v.1.0 Type Declaration Object will be ignored and the key name specified at the time of declaring this object will be preferred instead. |
PreferSwaggerOperationSummaryOverId | Boolean | By default, this is set to false . When true , we will give more precedence to Swagger Operation Object’s summary instead of operationId during endpoint name extraction |
AllowModelTypesWithNoFields | Boolean | By default, this is set to false . When true , model definitions containing no properties/fields will also be imported. |
ImportMultipleResponses | Boolean | By default, this is set to false . When true , any data related to multiple responses including additional types created for these responses will be loaded. |
LoadOneOfAsOptionalFields | Boolean | By default, this is set to false . When set to true , oneOf schemas will be combined and imported as a single model with all fields considered as optional. |
ImportArrayOfMapsAndMapOfArrays | Boolean | By default, this is set to false and schemas containing arrays of maps or maps of arrays will be treated as dynamic types during import. When set to true , however, such schema definitions will be imported and the type set accordingly. |
ImportTypeCombinators | Boolean | By default, this is set to true and type combining constructs like union types, anyOf , oneOf and not will be imported. Any extra types associated with these constructs will also be loaded. |
UseRamlUnionTypeAsOneOf | Boolean | By default, this is set to true and RAML v1.0 union types are loaded as the equivalent of oneOf type construct. If false , the union types are loaded as an equivalent of the anyOf type construct. |
Example:
{
"ImportSettings": {
"PreferJsonSchemaNameOverTitle": true,
"AppendParentNameForClashes": true,
"AutoGenerateTestCases": true
}
}
Export Settings
These settings lets you configure export to various formats e.g. enabling/disabling extensions when exporting to Swagger.
Export Settings Object
The available properties and their respective types are as follows:
Settings Type | Type | Purpose |
---|---|---|
ExportExtensions | Boolean | If true , any extensions, if supported in the selected export format, will be exported to the output file. |
GenerateModelSamples | Boolean | By default, when exporting to Postman (v1.0,2.0), parameter/request/response samples will be auto-generated (where needed) except when importing from WSDL or WADL. Sample generation can be enabled/disabled using this flag. |
UseDateTimeOnlyInRaml | Boolean | If true , then all date-time fields are exported with type datetime-only instead of datetime in RAML v1.0 . |
SetPostmanParamValuesAsVariables | Boolean | If true , auto-generated sample values for Postman params (query/path) will be stored inside collection variables instead of being directly embedded in the param definitions. The name of the variable will be the param’s name. The values stored in the variables can then be adjusted through the Variables section in Postman’s Collection editor. |
AddRefSiblingDataInAllOfSchema | Boolean | Any sibling data added alongside a $ref is ignored. If any data needs to be added, OpenAPI recommends using allOf to wrap both $ref and that additional data. By default, we ignore sibling data when exporting OpenAPI schemas. However, when set to true , $ref and the data will be added to allOf . |
EncodeUrlParamsInPostman | Boolean | Enable/disable request URL encoding when exporting to Postman. This is set to true by default. |
Example:
{
"ExportSettings": {
"ExportExtensions": true,
"GenerateModelSamples": true
}
}
Have questions? Submit a request.