Manual Chapter : Working with OpenAPI

Applies To:

Show Versions Show Versions


  • 17.0.0
Manual Chapter

Working with OpenAPI

Working with OpenAPI

You can use your existing OpenAPI (Swagger) specification file to quickly create an Application Security Manager security policy. Use the REST API to upload the specification file. When creating the security policy in the GUI, use the special API Security policy template. This streamlined template and the configurations contained in your OpenAPI specification file eliminate the need for further regular security policy configurations in ASM.
There is no support for OpenAPI file upload when sent with
OpenAPI / ASM integration is useful in a CI/CD environment. Using a CI/CD pipeline, the security policy can be regularly and automatically updated.
When using an API Security policy, regular traffic learning is disabled because the expected traffic configurations are already defined in the OpenAPI specification file. However, learning is enabled for the following violation groups:
  • HTTP protocol compliance
  • Evaluation techniques
  • Disallowed file types
  • Attack signatures
  • Meta characters
When an updated OpenAPI specification file is uploaded, all previous entities not in the updated file are erased from ASM with the exception of signatures and meta characters.
The basePath is used as the API gateway. Therefore, the basePath/path must be configured for the actual server where the API will be deployed. An incorrect basePath will prevent traffic from being routed to ASM.

Working with OpenAPI and security policy parameters

You can define API Security policy parameters in your OpenAPI specification file instead of in Application Security Manager under
Application Security
Parameters List
Add Parameter
. Certain parameter fields and configurations are disabled in the GUI. They are editable only in the OpenAPI specification file.


If you upload an OpenAPI / Swagger file to define your parameters, the parameter's
field is disabled. You must update the parameter location (and any other configurations) in the OpenAPI file and re-upload it. You cannot locally update parameters via the GUI.
The Location option
are specific to OpenAPI parameters.

Parameter Value Type

Parameter Value Type
object displays in the GUI as
JSON value
. In
Parameter Value Type
there is the option of
Array value
, specifying that the parameters are in an array. Array parameters can be used with path, query, header and form parameters, specifying that the parameters can appear in any location. An
Array value
enables the
Serialization Format
field. Also in
Parameter Value Type
there is the option of
Object value
, specifying that the parameters can appear in any location. This object value is defined in the OpenAPI file and is not editable from the GUI.


There is support for serialization options as defined in Swagger 2.0.

Mixed type array

Loading of array=mixed type is not supported. If one of the following constructs is used in the OpenAPI or Swagger file, the file will fail to load. Errors and warning from loading of an OpenAPI file or a Swagger file are written to /ts/log/asm_config_server.log.
  • Example 1
    type: array items: oneOf: -type: string -type: integer
  • Example 2
    # Array of Cats and Dogs type: array items: oneOf: - $ref: '#/components/schemas/Cat' - $ref: '#/components/schemas/Dog'
  • Example 3
    type: array items: {}

Working with OpenAPI and allowed HTTP URLs

You should not manually create allowed HTTP URLs in the GUI when working with an API Security policy template and Swagger file. Include the allowed HTTP URLs in the your Swagger file.
The URL attribute
can be used to filter traffic events related to a URL.
Body is Mandatory
will be enabled if
is defined as
by the OpenAPI spec for an endpoint.

Working with OpenAPI JSON schemas

You can create a JSON schema validation file to validate for your REST endpoints and protect
When writing your JSON schema, be strict with what is permitted and prohibited. Because even a strict schema can still generate false positives, ASM does not include traffic learning of the JSON schema traffic.
The JSON schema is validated when uploaded and any violations are noted. You can use more than 1 JSON schema file but each file must be uploaded separately and the JSON Profile Properties updated after each upload.
When using more than 1 JSON schema file, upload the file with
links first. An error is generated but uploading the subsequent files resolves the broken links error.
After a JSON schema is uploaded and selected, the
Parse Parameters
setting is disabled because the policy stops using any configured policy parameters and begins using the JSON parameters.

Creating an OpenAPI security policy

You use the API Security policy template and upload your OpenAPI configuration file to create an OpenAPI security policy.
  1. On the Main tab, click
    Application Security
    Security Policies
    Policies List
    The Policies List screen opens.
  2. Click
    Create New Policy
    You only see this button when no policy is selected.
  3. Enter a unique policy name.
  4. Make sure the
    Policy Type
  5. For the
    Policy Template
    API Security
    OpenAPI (Swagger) File
    field is now visible.
  6. Click
    Upload File
    to navigate to your OpenAPI specification file and upload it.
  7. Click
    to create the OpenAPI Security policy.