OpenAPI CodeGen Extensions

OpenAPI/Swagger (v2.0, v3.x) facilitates third-party vendors to implement tool-specific extensions. These extensions allow customizing behaviors beyond simple API definitions. We at APIMatic also offer extensions that are specific to Code Generation and can be specified within your OpenAPI definition file. These extensions allow you to customize the APIMatic code generation engine as per your requirements. The following documentation discusses the extensions available and how to use them.

Code Generation Settings and OpenAPI Extensions

In the case of Swagger/OpenAPI, we provide extensions that you can use within your OpenAPI definition to specify code generation settings and get the desired customizability. We also provide similar extensions for API Blueprint whose details can be viewed at API Blueprint Extensions. The extensions are supported by both the "Import" API operation, as well as by our Code Generation as a Service API.

CodeGen Extensions and How To Use Them

We offer the following CodeGen extensions:

CodeGen Settings
Advanced Settings for Endpoints
Additional Headers
Basic Authentication Extensions
OAuth 2.0 Extensions
Discriminator Value Extension
Enumeration Extensions
Datetime Extensions
Dynamic Response Extension
Exception Model Name Extension
Example Extensions
API Metadata Extensions
API Filtering Roles Extension
Applied Authentication Options Extension

CodeGen Settings

APIMatic offers numerous settings that enable you to configure generic code styling, endpoint settings, model settings, continuous integration settings, code branding options, etc. at the time of generating code. More details of these can be viewed at Code Generation Settings.

To specify these settings, you will need to use the CodeGen Settings extension. Using this extension simply involves using a property x-codegen-settings within the "Info" object. The "Info" object is used in OpenAPI/Swagger for providing metadata about the API. Details of this object can be viewed at Info Object (v2, v3). The x-codegen-settings property is an object that will look something like this:

"info": {
    ...,
    "x-codegen-settings": {
        "nullify404": true,
        "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,
        "enableJsonPassThroughForAny": true
    }
}

These settings will be globally applicable to all operations and schema definitions. Details of the properties available within this extension are given below:

Parameter	Type	Purpose
enableJsonPassThroughForAny	Boolean	Specifies whether the JSON should be passed through any type in the SDK.
generateAsyncCode	Boolean	When true, the CodeGen engine generates asynchronous C# and Java code.
useMethodPrefix	Boolean	When true, HTTP verbs are used as prefix for generated controller methods.
useModelPostfix	Boolean	When true, a postfix "Model" is appended to all classes generated from schemas.
useControllerPrefix	Boolean	When true, a prefix "Controller" is appended to all controllers generated from path groups.
controllerPostfix	String	This helps specify custom postfix for controller names.
useEnumPostfix	Boolean	When true, a postfix "Enum" is appended to all enumerations lifted from "allowedValues".
useConstructorsForConfig	Boolean	When true, configuration values e.g., authentication credentials, are accepted as controller constructor parameters. Otherwise, these values generate variables in a Configuration class.
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.
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.
collectParameters	Boolean	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	String	A valid C# namespace value to be used as the default namespace. Leave empty or null to automatically generate.
javaDefaultPackageName	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.
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.
phpComposerPackageName	String	This will set the name in composer.json file for PHP SDKs. You must provide a string with the format your-vendor-name/package-name.
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.
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"
enableAdditionalModelProperties	Boolean	When true, additional or unknown properties in the response JSON are collected into a dictionary.
nullify404	Boolean	When true, null response will be returned on the HTTP status code 404
useCommonSDKLibrary	Boolean	When true, a common library comprising of common classes is used by the generated SDKs
projectName	String	The name of the project for the Generated SDKs
preserveParameterOrder	Boolean	When true, parameter order is tried to be preserved in endpoints and models
generateInterfaces	Boolean	When true, interfaces for controller classes are generated in the generated SDKs
validateRequiredParameters	Boolean	When true, required API endpoint parameters are validated to be not null
timeout	Float	When set, the requests will timeout after the specified duration
storeTimezoneInformation	Boolean	Attempts to preserves timezone information when any date-time type is parsed. Timezone is also included as part of serialized data when such data is sent. By default, this will be `false` and date-time types with timezone will be normalized to UTC.
enableLogging	Boolean	Enabling this generates code in the SDKs for logging events in the API cycle using a library.
applyCustomizations	array[String]	List of customer-specific customizations to apply.
sortResources	Boolean	When true, this sorts endpoint groups, endpoints and models during code generation (SDKs and docs)
allowSkippingSSLCertVerification	Boolean	When true, it allow clients the option to make insecure endpoint calls that do not verify SSL certificate when using HTTPS
doNotSplitWords	array[String]	List of words that should not be split, regardless of the capitalization. The order determines priority, from highest to lowest.
enableGlobalUserAgent	Boolean	Enable this to send the UserAgent field as the user-agent header or APIMatic's branding user-agent if the UserAgent field is empty. Disabling this will NOT disable user-agent from being sent if its set as a additional header or in endpoint parameters as a header param.
returnCompleteHttpResponse	Boolean	If true, complete HTTP response including headers and status code will be returned
controllerNamespace	String	Name of controller namespace in SDK.
arraySerialization	String	Array serialization for primitive types (applicable to form and query params) . Valid values are `Indexed`, `UnIndexed`, `Plain`, `CSV`, `TSV`, `PSV`
responseMapping	Response Mapping Object	Response mapping strategy to use for mapping the HTTP response to the result passed to the endpoint caller in an SDK.
generateModels	Boolean	When true, model and enum classes will be generated in the SDKs.
generateExceptions	Boolean	When true, exception classes will be generated in the SDKs.
throwForHttpErrorStatusCodes	Boolean	When true, SDKs will throw an exception on HTTP error status codes. Alternatively, the SDK will not throw an exception but instead pass the error status code to the caller gracefully.
usageExampleEndpoint	Usage Example Endpoint Object	Allows the user to choose an endpoint for which to display a full usage example in the README.
isLatestVersion	Boolean	Using this, user can specify whether this SDK is the latest version or not. Enabling this will hide version number from install commands and package repository links.
shortCopyrightNotice	String	Using this, user can specify a copyright notice to prepend to all code files in an SDK. This setting will be ignored if the user is not allowed white-labelling.
licenseText	String	License text to use in place of the standard MIT License.
retryInterval	Float	Interval between endpoint call retries.
backoffFactor	Float	Exponential backoff factor for duration between retries.
statusCodesToRetry	array[Integer]	List of HTTP status codes to invoke retry on.
requestMethodsToRetry	array[String]	List of HTTP request methods (`GET`, `POST`, etc.) to invoke retry for.
userConfigurableRetries	Boolean	Whether SDK users should be able to configure retries or not.
pascalCaseEnumForCSharp	Boolean	Enabling this will convert uppercase enum elements into pascal case in the CSharp SDK.
pascalCaseEnumForTypeScript	Boolean	Enabling this will convert uppercase enum elements into pascal case in the TypeScript SDK.
disableMultipleAuth	Boolean	Enabling this will disable support for multiple authentication schemes in SDK.
addSingleAuthDeprecatedCode	Boolean	Specifies whether deprecated code for single authentication scheme should be added to the SDK.
errorTemplates	Map [String, String]	Custom templated messages that can be provided for overriding default exception messages thrown in SDKs for error responses. More details can be found here.

Advanced Settings

APIMatic allows further customization of endpoints (called operations in OpenAPI) through the Advanced Settings extensions. These extensions can be specified inside the Operation Object (v2, v3).

Two extensions are currently available which are defined below:

Operation Settings
Multiple Body Parameters Setting
Deprecation Details

Operation Settings

These settings are specified using property name x-operation-settings. See an example as follows:

"paths": {
    "/pets": {
        "post": {
            ...
            "operationId": "addPet",        
            "x-operation-settings": {
                "collectParameters": false,
                "allowDynamicQueryParameters": true,
                "allowDynamicFormParameters": false,
                "isMultiContentStreaming": false,
                "methodName": "create",
                "groupName": "pets",
                "forceRetries": true
            }
        }
    }
}

Details of the properties available within this extension are given below:

Property	Type	Purpose
collectParameters	Boolean	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	Boolean	When true, a postfix "Model" is appended to all classes generated from schemas.
allowDynamicQueryParameters	Boolean	When true, the generated method has an additional Map input, which may contain dynamic number of query parameters as Key-Value pairs.
allowDynamicFormParameters	Boolean	When true, the generated method has an additional Map input, which may contain dynamic number of form parameters as Key-Value pairs.
isMultiContentStreaming	Boolean	When true, it indicates that this operation is a streaming endpoint. For example, Twitter Streaming API endpoints.
parameterCollectionName	String	Represents the name of the model that represents CollectedParameters.
methodName	String	When specified, it is used instead of the operation name (extracted from the operation ID/summary) for generating method names in SDKs. While an operation ID in OpenAPI needs to be unique across the complete API, the method name should ideally be unique among all operations in a particular path item only.
responseMapping	Response Mapping Object	Response mapping strategy to use for mapping the HTTP response to the result passed to the endpoint caller in an SDK. This will override the response mapping specified in the CodeGen settings if any.
groupName	String	When specified, it is used for generating the endpoint's group name in SDKs/docs instead of the first tag name specified in an Operation object.
forceRetries	Boolean	When set to `true`, the SDKs can force retry an endpoint regardless of whether it is idempotent or not. If `false`, the endpoints will not be retried. By default, only idempotent endpoints are retried.
errorTemplates	Map [String, String]	Custom templated messages that can be provided for overriding default exception messages thrown in SDKs for error responses. More details can be found here. Note, that an error template specified at operation level will override the one specified under CodeGen settings for the same error template key.
skipAdditionalHeaders	Boolean	When set to `true`, any additional headers applied at API level will be ignored for the current endpoint. This is set to `false` by default.

Multiple Body Parameters Setting:

Since OpenAPI does not allow defining multiple body parameters, you can use this setting to help unwrap any body parameter into multiple body parameters for Code Generation purposes. Essentially, this setting is a boolean flag specified using the name x-unwrap-body inside the Operation object. You can simply define a schema in the OpenAPI/Swagger file (generally inside #/definitions or #/components/schemas depending on the OAS/Swagger version) where schema fields will represent the body parameters. Link this schema in the body parameter definition of the Operation object and set the flag to true. We will then automatically unwrap the body schema into multiple body parameters during the import process.

A usage example of the flag described above is shown below:

"post": {
    "summary": "Multiple body parameters",
    "parameters": [{
        "name": "body",
        "in": "body",
        "required": true,
        "schema": {
            "$ref": "#/definitions/bodySchema"
        }
    }],
    "x-unwrap-body": true
}

Here the schema fields of bodySchema represent the actual body parameters.

Deprecation Details:

This extension can be used inside the Operation object using key x-deprecation-details. This extension allows you to define additional details for your operation if it has been declared as deprecated using the OAS deprecated property. The properties available for describing the deprecated operation in more detail are:

Property	Type	Purpose
message	String	Helps describe any additional information about the deprecated operation e.g. reason, alternative, etc.
deprecatedInVersion	String	Helps specify the version in which this item was deprecated.

A usage example of the above extension is given below:

"post": {
    ...
    "operationId": "addPet",
    "summary": "Deprecated operation",
    "deprecated": true,
    "x-deprecation-details": {
        "message": "This operation is deprecated. Use createPet",
        "deprecatedInVersion": "2.0"
    }
}

Additional Headers:

APIMatic allows defining global headers that are sent with every API call using the Addition Headers extension. These headers are in addition to any headers required for authentication or defined as parameters. These headers can be specified inside the Security Scheme Object (v2, v3) using property name x-additional-headers. See an example below:

OpenAPI 2.0
OpenAPI 3.x

"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"
            }
            ...
        ]
    }
}

"securitySchemes": {
    "basicAuth": {
        "type": "http",
        "scheme": "basic",
        "x-additional-headers": [
            {
                "name": "api-version",
                "description": "The version number indicator for the API",
                "schema": {
                    "default": "1.1"
                }                
            },
            {
                "name": "sdk-version",
                "description": "The version number indicator for the SDK",
                "schema": {
                    "default": "1.1.0.1"
                }
            }
            ...
        ]
    }
}

An additional header is defined using a subset of the properties of the Parameter Object (v2, v3). The available properties are:

Property	Type	Purpose
name	String	Name of the header
description	String	Any details regarding the header
default	String	Any default value for the header

Basic Authentication Extensions

By default, basic authentication requires username and password as input parameters. If you need to override the names of these parameters for code generation, you can use the extensions described below:

Extension	Type	Description
`x-rename-username-as`	String	The alternate name for `username` parameter e.g. `name`
`x-rename-password-as`	String	The alternate name for `password` parameter e.g. `secret`

Both the above extensions can be used inside the Security Scheme Object (v2, v3) as follows:

OpenAPI 2.0
OpenAPI 3.x

"securityDefinitions": {
    "basicAuth": {
        "type": "basic",
        "x-rename-username-as": "name",
        "x-rename-password-as": "secret"
    }
}

"securitySchemes": {
    "basicAuth": {
        "type": "http",
        "scheme": "basic",
        "x-rename-username-as": "name",
        "x-rename-password-as": "secret"
    }
}

OAuth 2.0 Extensions:

APIMatic also offers several extensions to help you configure your OAuth 2.0 security definition. For v2.0, you can use these extensions inside the Security Scheme Object and for v3.x inside the OAuth Flow Object as follows:

OpenAPI 2.0
OpenAPI 3.x

"securityDefinitions": {
    "oauth2": {
        "type": "oauth2",
        "flow": "password",
        "tokenUrl": "http://example.com/tokenurl",
        "x-skip-client-authentication": false,
        "x-oauth2-clientid-example": "clientid",
        "x-oauth2-clientsecret-example": "clientsecret",
        "x-oauth2-username-example": "username",
        "x-oauth2-password-example": "password"
    }
}

"securitySchemes": {
    "oauth2": {
        "type": "oauth2",
        "flows": {
            "password": {
                "tokenUrl": "http://example.com/tokenurl",
                "x-skip-client-authentication": false,
                "x-oauth2-clientid-example": "clientid",
                "x-oauth2-clientsecret-example": "clientsecret",
                "x-oauth2-username-example": "username",
                "x-oauth2-password-example": "password",
                "x-allow-additional-oauth-fields": true,
                "x-additional-oauth-fields": {
                  "prop1":{
                    "type": "string"
                  },
                  "prop2":{
                    "type": "integer"
                  }
                }
            }
        }
    }
}

The detailed explanation of all these extensions is given below:

Extension	Type	Description	Applicable to Flows
`x-skip-client-authentication`	Boolean	The OAuth 2.0 flow of resource owner password credentials will normally involve client app authentication using Client Id and Client Secret. However, if you want to skip this authentication for Code Generation purposes, you can set its value to `true`	`password`
`x-oauth2-clientid-example`	String	Specifies a value that can be used as an example or demo client ID	`*password`, `implicit`, `application`, `accessCode`
`x-oauth2-clientsecret-example`	String	Specifies a value that can be used as an example or demo client secret	`*password`, `implicit`, `application`, `accessCode`
`x-oauth2-username-example`	String	Specifies a value that can be used as an example or demo client username	`password`
`x-oauth2-password-example`	String	Specifies a value that can be used as an example or demo client password	`password`
`x-allow-additional-oauth-fields`	Boolean	When enabled, allows additional properties return in OAuth 2.0 flows.	`password`, `implicit`, `application`, `accessCode`
`x-additional-oauth-fields`	Object	Specifies an object of properties returned in OAuth 2.0 flow.	`password`, `implicit`, `application`, `accessCode`

The extension is not applicable to flow password if x-skip-client-authentication is set to true.

Discriminator Value Extension

OpenAPI makes use of a property discriminator to support polymorphism in custom types. As per OpenAPI, the value of this property must be the name of the parent model or the children models depending on which type the object represents. However, we allow our users to specify a custom discriminator value using the APIMatic's Discriminator Value extension. This value will override the default custom type name.

Usage

The extension is used through the x-discriminator-value property.

Property	Type	Purpose
`x-discriminator-value`	String	Custom discriminator value

For OpenAPI 1.2, the extension can be used inside the Model Object while for 2.0, it can be used inside the Definitions Object. In case of OpenAPI 3.x, the extension can be used inside the Discriminator Object. All of this is illustrated in the examples below:

OpenAPI 1.2
OpenAPI 2.0
OpenAPI 3.x

"Pet": {
    "id": "Pet",
    "required": [
        "name",
        "petType"
    ],
    "properties": {
        "name": {
            "type": "string"
        },
        "petType": {
            "type": "string"
        }
    },
    "subTypes": ["Cat"],
    "discriminator": "petType",
    "x-discriminator-value": "GenericPet"
}

"Pet": {
    "type": "object",
    "required": [
        "name",
        "petType"
    ],    
    "properties": {
        "name": {
            "type": "string"
        },
        "petType": {
            "type": "string"
        }
    },
    "discriminator": "petType",
    "x-discriminator-value": "GenericPet"
}

"Pet": {
    "title": "Pet",
    "required": [
        "name",
        "petType"
    ],
    "type": "object",
    "properties": {
        "name": {
            "type": "string"
        },
        "petType": {
            "type": "string"
        }
    },
    "discriminator": {
        "propertyName": "petType",
        "x-discriminator-value": "GenericPet"
    }
}

Enumeration Extensions

We currently provide two extensions to let you enhance the models we generate from your enumerations. These are:

Extension	Type	Description	Applicable to OpenAPI/Swagger Objects
`x-enum-elements`	Enum Element Object	Provide additional meta-data for your enumerations by assigning a unique name for each element of your enum as well as specify a brief description for each	Parameter Object, Items Object, Header Object, Schema Object (v2, v3)
`x-enum-model-name`	String	Specify a custom name for the enumeration model to be generated	Parameter Object when `in` is not set to `body`. For other objects, use `title` for this purpose

Usage

The following example demonstrates the usage of both extensions in a Parameter Object:

{
  "name": "numbers",
  "in": "query",
  "required": true,
  "type": "string",
  "enum": [
    "1",
    "2",
    "3",
    "4"
  ],
  "x-enum-elements": [
    {
      "name": "One",
      "description": "First element" 
    },
    {
      "name": "Two",
      "description": "Second element"
    },
    {
      "name": "Three",
      "description": "Third element"
    },
    {
      "name": "Four",
      "description": "Fourth element"
    }
  ],
  "x-enum-model-name": "Number Elements"  
}

Datetime Extensions

You can specify various date-time formats using our editor, the details of which are available at DateTime Formats. OpenAPI supports only one of these formats i.e. Rfc3339. To let you make use of other datetime formats, we provide custom formats which you can specify through the format property at the time of defining a type. As per OAS (v2, v3), the format property is an open string-valued property, and can have any value to support documentation needs.

Taking advantage of the above, we make the following formats available to help you finely define the date-time type:

Name	Description
`date-time`	Supported by OpenAPI/Swagger by default. Represents datetime Rfc3339 format
`date-time-rfc1123`	Helps represent datetime that uses Rfc1123 format
`unix-timestamp`	Helps represent datetime using Unix or Epoch time

Dynamic Response Extension

APIMatic supports type Dynamic for success responses where type schema is not known or cannot be easily defined. To use this type inside any version of Swagger, you can use our extension x-is-dynamic inside the response schema as follows:

{
    "responses": {
      "201": {
        "description": "Successful operation",
        "schema": {
          "type": "object",
          "x-is-dynamic": true
        }
      }
    }
}

Exception Model Name Extension

We autogenerate exceptions models from the error response schema definitions to provide better support for handling API errors in generated code. By default, the models generated this way use the original schema's name/title and have a _Error postfix attached to them. You can, however, choose to override the autogenerated name with one of your own using our x-exception-model-name extension in the OpenAPI's Schema Object (v2, v3).

Name	Type	Description
`x-exception-model-name`	String	When set, this name will override the default name assigned to an auto-generated exception model.

Example:

{
  "paths": {
    "/pets": {
      "get": {
        "operationId": "getPets",
        .....................
        "responses": {
          "400": {
            "description": "Unexpected error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BadRequest"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "BadRequest": {
        "x-exception-model-name": "ErrorResponse",
        "type": "object",
        "properties": {
          "code": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      }
    }
  }
}

In the above example, the exception model imported into APIMatic will be named ErrorResponse instead of BadRequest_Error.

Example Extensions

Swagger 2.0 does not have support for parameter level examples. If you need to specify examples for the Parameter Object, you can do so by using our extension described below:

Extension	Type	Description
`x-example`	Any	Example value for the parameter

{
    "name": "param1",
    "in": "query",
    "required": false,
    "type": "string",
    "x-example": "example value for param1"
}

API Metadata Extensions

The Info Object in OpenAPI (v2, v3) allows providing metadata about the API. We also offer some extensions that lets our users specify additional information about their API using this section.

Extension	Type	Description
`x-image-uri`	String	An absolute url that points to a display image for the API

Example

  "info": {
    "version": "1.1",
    "title": "Swagger Petstore",
    "x-image-uri": "http://example.com/image.png"
  }

API Filtering Roles Extension

APIMatic supports role-based API filtering. If you choose to filter your API by roles, the resulting portal will only contain documentation for those endpoints available to the specific role(s). It works by matching endpoint-level tags with tags associated with specific roles. Information about the endpoint level tags comes from tags supported in OpenAPI at Operation level. However, to help specify information about available roles in the API, we support an extension called x-roles in the root OpenAPI object. See an example of it below:

Example Usage

info:
  version: 1.0.0
  title: Swagger Petstore
x-roles:
  - name: private-role
    id: "2"
    tags: 
      - pets
    description: private role  

In below case, role with id 2 will have access to operations with tags containing "pet" but not those tagged as "store".

  /pet:
    post:
      tags:
      - "pet"
      summary: "Add a new pet to the store"
    ...............
  /store/inventory:
    get:
      tags:
      - "store"
      summary: "Returns pet inventories by status"
      description: "Returns a map of status codes to quantities"
      operationId: "getInventory"
    .............  

Details of the properties available within this extension are given below:

Property	Type	Purpose
name	String	Name of the role.
id	String	Unique identifier of the role.
description	String	Provides more details about the role.
tags	array[String]	List of String-valued tags associated with the role.

Applied Authentication Options Extension

You can extend the security information you apply globally or at operation level by adding additional metadata that can help provide more details about the security being applied. This metadata can be added using our extension x-security-options-meta which is applicable at the root OpenAPI/Swagger Object (v2, v3) and the Operation Object (v2, v3).

Details of the properties available within this extension are given below:

Property	Type	Purpose
name	String	A user-friendly name for the security option.
description	String	Provides more details about the security option.

Example Usage

 security:
   - {}
   - apiKey: []
 x-security-options-meta:
   - name: No Authentication
     description: Authentication can be skipped. This will allow limited functionality, however.
   - name: API Key
     description: Pass the API key provided to you in your account settings. This will allow you full access to functionality.

danger

The number of items inside the extension must match the number of options in the security property else the extension data will be considered invalid or incomplete.

Response Mapping Object

Response Mapping Object is designed as a discriminated union with Type as the discriminator.

Currently, two types are supported:

Simple

Matches the current behavior i.e response from endpoint is treated as the result or error.

{
    "Type": "Simple"
}

Field-Based

Data is extracted from a nested-field in the response's JSON object. Additionally, an error field can also be specified. Each element of the DataField or ErrorField corresponds to one level of nesting and implies the name of the field to be accessed for the data.

{
    "Type": "FieldBased",
    "DataField": ["nested", "data"],
    "ErrorField": ["error"]
}

Usage Example Endpoint Object

Details of the properties available within this object are given below:

Parameter	Type	Purpose
EndpointName	String	`Name` of the chosen endpoint.
EndpointGroupName	String	`Group` name of the chosen endpoint.
Description	String	An optional description to show along with the usage example.

Example

{
    "EndpointName": "Get Pet",
    "EndpointGroupName": "Pets"
}

Error Templates

Error templates are custom templated messages that can be provided for overriding default exception messages thrown in SDKs for error responses. They can be defined using a map like structure as shown below:

  "errorTemplates": {
      "401": "Response returned an error with status code {$statusCode}.",
      "402": "Error occurred: {$response.body#/errors/0/reason}",
      "5XX": "Internal server error, Code: {$statusCode}.", //this error message will be thrown for all error responses with status codes belonging to the 5XX range.
      "0": "An error occurred. Code: {$statusCode}" //this error message will be thrown for all error responses that are not covered explicitly in the error templates.
  }

Here,

Key of an error template: Should be a valid HTTP error status code (400 - 599) or range (e.g. 4XX, 5XX). The key can be set to 0 to represent any undeclared error codes.
Value of an error template: The exception message that the SDK must return in case of an error response belonging to the range specified in the template key. The error message defined here has support for templates that are replaced by real data at runtime. More details about the required syntax for the message can be found in the next section.

Error Template Message Syntax

The error template message is capable of supporting template expressions that hold placeholders which are replaced with actual data at realtime. A template expression must start and end with curly braces {}. The available placeholders that can be used are listed below:

Placeholder	Details
$statusCode	This is replaced by the actual response's status code at runtime e.g. for an error response 401, the SDK exception message with a provided error template of `Response returned an error with status code {$statusCode}.` will become `Response returned an error with status code 401.`
$response.header.headerKey	This is replaced with the content of the response header whose name's specified in place of the `headerKey` part of the placeholder e.g. for a response with header `X-Cache` set to `Hit`, the SDK exception message with a provided error template like `Could not fetch response data. Cache: {$response.header.X-Cache}` will become `Could not fetch response data. Cache: Hit`.
$response.body#JsonPointer	This placeholder is replaced with the content of the response body. `#JsonPointer` is an optional segment of the placeholder to help retrieve a specific part of the JSON response body using JSON pointer syntax. If the value is non-primitive, it will be serialized first e.g. for an error response with body `{"error": {"reason": "Unauthorized"}}`, the SDK exception message for provided error template like `Response returned with error: {$response.body#error/reason}` will become `Response returned with error: Unauthorized`.

Code Generation Settings and OpenAPI Extensions​

CodeGen Extensions and How To Use Them​

CodeGen Settings​

Advanced Settings​

Operation Settings​

Multiple Body Parameters Setting:​

Deprecation Details:​

Additional Headers:​

Basic Authentication Extensions​

OAuth 2.0 Extensions:​

Discriminator Value Extension​

Usage​

Enumeration Extensions​

Usage​

Datetime Extensions​

Dynamic Response Extension​

Exception Model Name Extension​

Example Extensions​

API Metadata Extensions​

Example​

API Filtering Roles Extension​

Example Usage​

Applied Authentication Options Extension​

Example Usage​

Response Mapping Object​

Simple​

Field-Based​

Usage Example Endpoint Object​

Example​

Error Templates​

Error Template Message Syntax​

Code Generation Settings and OpenAPI Extensions

CodeGen Extensions and How To Use Them

CodeGen Settings

Advanced Settings

Operation Settings

Multiple Body Parameters Setting:

Deprecation Details:

Additional Headers:

Basic Authentication Extensions

OAuth 2.0 Extensions:

Discriminator Value Extension

Usage

Enumeration Extensions

Usage

Datetime Extensions

Dynamic Response Extension

Exception Model Name Extension

Example Extensions

API Metadata Extensions

Example

API Filtering Roles Extension

Example Usage

Applied Authentication Options Extension

Example Usage

Response Mapping Object

Simple

Field-Based

Usage Example Endpoint Object

Example

Error Templates

Error Template Message Syntax