Open API Profile (3.3)

Owned by Jenni Wallin
Last updated: Feb 15, 2024 by Kevin Wu
1 min read

If you want to use Open API 3.0 with HTTP/2 agents, you require an Open API profile configuration. You select the profile that you configure in the HTTP/2 Server agent configuration. In the Open API profile configuration, you import your OpenAPI specification file and view any other included files defined by the specification.

  • All schemas that require a UDR must be named. Due to a limitation in the third party parsing library used by OpenAPI, unnamed schemas cannot be detected and will not generate a corresponding UDR. Therefore, you must name all schemas that require a UDR.

  • Field names in the yaml specification file containing the following symbols will be replaced with unique string of characters during the UDR generation process as shown below:

    • @ -> _40_

    • . -> _2E_

    • - -> _2D_

For example, the field "test-name" will be converted into "test_2D_name" as a UDR.

  • All tab indentations found in the Open API yaml files will be replaced with two spaces. 

Configuration

The OpenAPI profile consists of the following tabs:

General Tab

Setting

Description

Import

Imports the Open API specification file from the local file directory of the desktop or desktop client.

Click on this button again after a file has been imported, to import another Open API specification file to overwrite the previously imported specification file.

View

Opens the selected Open API schema file. 

Referenced Files

Lists the yaml files that are already imported into the Open API profile. Clicking on any of the records in the list will allow you to view the yaml file or remove it from the profile.

Clicking on the Import button on the Reference Files will allow you to import the reference files for the main Open API specification file as well as any other reference files that are required.

Refreshing the content.

To refresh the content of the imported API file or the contents of other included files, the imported file will have to be imported once again.

Importing Open API Specification Files

  1. Users can choose to import or upload the yaml specification files via the following:

    1. Browse and select from local directory

    2. Drag and drop the file(s) to the Import Open API file dialog box

      openapi_importyaml.png

  2. For any files that contain missing dependencies, you can choose to import or upload the referenced files via the following:

    1. Browse and select from local directory

    2. Drag and drop the file(s) to the Import referenced Open API file(s) dialog box

    openapi_import_reffiles.png

  3. To view each Referenced file, select the .yaml file from the table and click View Schema. 

  4. To remove the .yaml file from the table, click Remove.

Advanced Tab

Setting

Description

Ignore Read Only Tag

Select this option to ignore the readOnly tag in the schema file.

Info!

When UDRs are generated from the OpenAPI specification file, some UDR fields found in the response body are marked as read-only. This prevents HTPP/2 Server from setting these fields in the APL to generate a proper response.

By selecting this option, it allows HTTP/2 Server agents to be able to set the readOnly fields in the APL for use cases that require a response from the HTTP/2 Server agent. 

Add “additionalProperties: false” to component schemas

Select this option to add the “additionalProperties: false” to each component in the schema file.

Limitations 

This section lists the limitations that users may encounter when using the OpenAPI profile.

OpenAPI specification schema which contains oneOf tag will be decoded as a map instead of a UDR

In the following example, the SubscriptionData schema contains the subscrCond property with oneOf tag:

Example: SubscriptionData schema contains the subscrCond with oneOf tag

SubscriptionData:
      description: Information of a subscription to notifications to NRF events, included in subscription requests and responses
      type: object
      required:
        - nfStatusNotificationUri
        - subscriptionId
      properties:
        nfStatusNotificationUri:
          type: string
        reqNfInstanceId:
          $ref: 'TS29571_CommonData.yaml#/components/schemas/NfInstanceId'
        subscrCond:
          oneOf:
            - $ref: '#/components/schemas/NfInstanceIdCond'
            - $ref: '#/components/schemas/NfInstanceIdListCond'
            - $ref: '#/components/schemas/NfTypeCond'
            - $ref: '#/components/schemas/ServiceNameCond'
            - $ref: '#/components/schemas/AmfCond'
            - $ref: '#/components/schemas/GuamiListCond'
            - $ref: '#/components/schemas/NetworkSliceCond'
            - $ref: '#/components/schemas/NfGroupCond'
            - $ref: '#/components/schemas/NfSetCond'
            - $ref: '#/components/schemas/NfServiceSetCond'
            - $ref: '#/components/schemas/UpfCond'
            - $ref: '#/components/schemas/ScpDomainCond'
            - $ref: '#/components/schemas/NwdafCond'
            - $ref: '#/components/schemas/NefCond'

The subscrCond is a schema of NfSetCond but it is decoded as a map with key value pair as shown below:

Example: SubscriptionData schema decoded in the APL:

[openapi.issue_http.OAPI_NrfMgt.udr.SubscriptionData]
  nfStatusNotificationUri: http://localhost/dummy
  subscriptionId: 123456
  subscrCond: {nfSetId=MU01}

To retrieve the value of the map, enter the following code in APL:

string ID = mapGet((map<string, any>)subscriptionData.subscrCond, "nfSetId");
debug(ID);

The debug output is as follows:

MU01