Skip to main content


         This documentation site is for previous versions. Visit our new documentation site for current releases.      
 

Best practices for generating OpenAPI Specification documentation

Updated on April 6, 2022

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

To generate accurate and complete OAS documentation in your application, review the following best practices:

  • Use the following options in the Map to and Map from fields to generate a complete schema:
    • Automation input/output
    • Clipboard
    • JSON

      If you select Use JSON data transformation in the Mapping method field, the system generates the schema based on the properties defined in the JSON data transform that you provide.

      If you use the auto-map action in the JSON data transform, the system generates all relevant records in the OAS documentation. To skip any property from populating in the OAS, add the property in the Fields to skip when auto-mapping section of the JSON data transform Settings tab. For more information, see Configuring the JSON data transforms settings column on the Data Transform form.

  • Avoid using the following options in the Map to and Map from fields. If you use the XML or HTML options, the generated schema only displays the type. For example, for an XML Parse input, the schema displays type:XML. For all of the other options, the system does not generate a schema.
    Map to options
    XML Parse
    HTML Postdata
    Delimited Parse Rule
    Parse Structured
    Functions created in the MapTo library
    Map from options
    XML Stream
    HTML Stream
    HTML Frame
    Functions created in the MapFrom library
  • If you use the Clipboard option, 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.
  • If you use the Clipboard option, 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, the system does not generate a schema.
  • Use valid property references, for example, .Prop1.Prop2.
  • Use page, page list, and string mode properties. Use of other modes is not recommended, even if you use a property reference.
  • Specify 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 condition generates.
    • If a response condition uses a property or parameter reference for its HTTP code, the response condition 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 response condition generates.

    For more information, see Service REST methods.

  • Previous topic OpenAPI Specification in Pega Platform
  • Next topic Generating OpenAPI Specification documentation for application-specific REST APIs

Have a question? Get answers now.

Visit the Support Center to ask questions, engage in discussions, share ideas, and help others.

Did you find this content helpful?

Want to help us improve this content?

We'd prefer it if you saw us at our best.

Pega.com is not optimized for Internet Explorer. For the optimal experience, please use:

Close Deprecation Notice
Contact us