Advanced details and limitations of generating OpenAPI Specification documentation

OpenAPI Specification (OAS) documentation is automatically generated for every REST service rule. The OAS documentation of each REST service included in a service package are combined into a single OAS document.

Limitations

The following limitations apply to generating OAS documentation in your application.

  • Only use simple property references, for example, .Prop1.
  • Only use page, pagelist, and string mode properties. Other modes are not supported, even if you use a simple property reference.
  • If you use Clipboard, avoid setting the Map to key and Map from key values to a top-level page, for example, MyUndefinedPage. If you use an undefined page, inaccurate OAS documentation is generated.
  • The following MapTo options are not supported:
    • XML Parse
    • HTML Postdata
    • Delimited Parse Rule
    • Parse Structured
    • Functions created in the MapTo library
  • The following MapFrom options are not supported:
    • XML Stream
    • HTML Stream
    • HTML Frame
    • Functions created in the MapFrom library

Advanced details for generating comprehensive OAS documentation

Review the following additional information to ensure that you generate accurate and useful OAS documentation:

  • Avoid setting the Map to key and Map from key values to a parameter reference in your REST service rules. If you use a parameter reference, the generated schema displays type:string.
  • Ensure that you have specified an HTTP response code in the response condition of each of the REST service rules that are included in your service package. Note the following:
    • If multiple response conditions use the same HTTP code, only the first one is generated.
    • If a response condition uses a property or parameter reference for its HTTP code, it is set as default in the generated OAS.
    • If multiple response conditions use a property or parameter reference for the HTTP code, only the first one is generated.

    For more information, see Service REST form - Completing the Methods tab.