OpenEdge.Web.DataObject.Writer.OpenAPI30ServiceWriter
- Last Updated: August 18, 2026
- 15 minute read
- OpenEdge
- Version 12.8
- Documentation
|
Method Summary
| Options | Name | Purpose | |
|---|---|---|---|
| AddNullableProperty (JsonObject) |
/**
Adds nullable property to a schema object for OpenAPI 3.0.x compliance.
This method is designed to be overridden in later spec versions (e.g., 3.1.x, 3.2.x)
where nullable handling differs per JSON Schema Draft 2020-12.
@param JsonObject The schema object to add nullable property to
*/
|
||
| AddPropertyWithSchema (DataObjectService, JsonObject, character, character, character) |
/**
Adds a property to a properties object, using JSON Schema if available.
Matches schemas by ABL parameter name for consistency with Body element handling.
@param DataObjectService The service containing potential JSON schemas
@param JsonObject The properties object to add to
@param character The property name (wire format/serialize-name) for JSON output
@param character The ABL parameter name for schema lookup
@param character The ABL data type for fallback
*/
|
||
| ApplyFieldFormat (JsonObject, character) |
/**
Applies format to a schema object for type validation hints.
This method is designed to be overridden in later spec versions (e.g., 3.2.0)
to handle format differently, particularly for binary data which uses
contentEncoding/contentMediaType in JSON Schema Draft 2020-12.
@param JsonObject The schema object to apply format to
@param character The format value (e.g., 'date', 'date-time', 'int32', 'binary')
*/
|
||
| ApplyUserContext () |
/**
Applies user-provided context (document version, direct server) to the OpenAPI document.
Called automatically by Open() after the JsonObject structure is created.
Modifies the existing JsonObject to insert direct server as first entry and update version.
*/
|
||
| Close () |
/**
Finalizes and closes the writer.
Cleans up cached Principal object and performs final service cleanup.
Public override to satisfy interface contract.
*/
|
||
| Progress.Json.ObjectModel.JsonObject CreateArrayFieldSchema (handle, character) |
/**
Creates a JSON Schema for an ABL array field (extent).
Produces an array type with items schema including maxItems based on extent size.
@param handle A valid buffer-field handle with extent
@param character Comma-delimited list of unique field names for required flag
@return JsonObject The JSON Schema object for the array field
*/
|
||
| Progress.Json.ObjectModel.JsonObject CreateFieldSchema (handle, character) |
/**
Creates a JSON Schema for a single ABL field.
Includes type, title, description, nullable, required, and format properties.
@param handle A valid buffer-field handle
@param character Comma-delimited list of unique field names for required flag
@return JsonObject The JSON Schema object for the field
*/
|
||
| CHARACTER FieldInfo (character, character) |
/**
Converts ABL data type to JSON Schema type and format.
Maps ABL types to OpenAPI/JSON Schema equivalents with appropriate format hints.
@param character ABL data type name
@param character OUTPUT format string (e.g., 'date', 'date-time', 'int32', 'int64', 'binary')
@return character JSON Schema type ('string', 'integer', 'number', 'boolean', 'object', 'array')
*/
|
||
| OpenEdge.Security.Principal GetCurrentPrincipal () |
/**
Gets the current user's Principal, with caching for performance.
Called once during Open() to avoid repeated Import() calls.
@return Principal The current user's Principal, or unknown if not authenticated
*/
|
||
| Progress.Json.ObjectModel.JsonObject GetJsonSchema (DataObjectService, character) |
/**
Retrieves a JSON Schema definition from the service's map schemas.
@param DataObjectService The service containing the map schemas
@param character The schema name to retrieve
@return JsonObject The JSON Schema definition, or unknown if not found
*/
|
||
| Progress.Json.ObjectModel.JsonObject GetPathJson (DataObjectService, character, MethodEnum) |
/**
Retrieves or creates a path operation JSON object for a specific URI and HTTP method.
Constructs the full path from service name and URI, creates the operation object
with standard sections (tags, summary, description, operationId, parameters, responses, security).
@param DataObjectService The service containing the operation
@param character The operation URI path
@param MethodEnum The HTTP method for the operation
@return JsonObject The operation object for the specified path and method
*/
|
||
| OpenEdge.Web.DataObject.Writer.IOpenAPIServiceWriter IncludeRoleRequirements () |
/**
Enables the inclusion of role requirements in the OpenAPI document.
By default, role names are not exposed for security reasons.
Call this method to opt-in to documenting specific role requirements
either via standard OpenAPI security requirements or x-required-roles extension.
Uses fluent API pattern to allow method chaining.
@return IOpenAPIServiceWriter Returns this instance for method chaining
*/
|
||
| LOGICAL IsOperationAuthorized (MappedOperation) |
/**
Checks if the current user is authorized to access an operation.
If the operation has no ACL defined, it is considered accessible to all.
If ACLs are defined, the user must have at least one of the required roles.
Uses cached Principal for performance across multiple operation checks.
@param MappedOperation The operation to check authorization for
@return logical TRUE if the user is authorized or no ACLs are defined, FALSE otherwise
*/
|
||
| MarkRequiredField (JsonObject, character, character) |
/**
Marks a single field schema as required for OpenAPI 3.0.x compliance.
Called per-field from CreateFieldSchema and CreateArrayFieldSchema when
the field belongs to a unique index.
This method is designed to be overridden in later spec versions (e.g., 3.1.x)
where required is expressed as an array on the parent items object instead.
@param JsonObject The field schema object to mark as required
*/
|
||
| MarkRequiredFields (JsonObject, character) |
/**
Marks required fields at the table (items) level after all fields are built.
Called once per table from WriteTable with the complete unique field list.
This is a no-op in OpenAPI 3.0.x â'' required is applied per-field by MarkRequiredField.
Designed to be overridden in later spec versions (e.g., 3.1.x) where required
is expressed as a 'required' array on the parent items schema object.
@param JsonObject The items schema object of the table
@param character Comma-delimited list of unique (required) field names
*/
|
||
| Open () |
/**
Initializes the writer and creates the root OpenAPI document structure.
Creates a new JsonObject representing the OpenAPI document if not already present.
After creating the structure, applies any user-provided context (version, servers).
*/
|
||
| RemoveEmptyServices () |
/**
Removes services and tags that have no accessible operations.
Called after all operations have been written, to clean up empty services.
*/
|
||
| CHARACTER ScrubPunctuation (character) |
/**
Sanitizes a character value to ensure compatibility with code generators and external tooling.
Replaces problematic characters (dots, slashes, backslashes, spaces) with underscores.
Ensures the resulting identifier is safe for use as a method/function name in most languages.
@param character The raw character value to sanitize
@return character The scrubbed character value with safe characters only
*/
|
||
| OpenEdge.Web.DataObject.Writer.IOpenAPIServiceWriter SetDocumentVersion (character) |
/**
Sets the document API version for the OpenAPI specification.
Uses fluent API pattern to allow method chaining.
Call before Open() to override the default version.
@param character The API version string (eg. "3.1.4")
@return IOpenAPIServiceWriter Returns this instance for method chaining
*/
|
||
| OpenEdge.Web.DataObject.Writer.IOpenAPIServiceWriter SetServer (character, character, integer, character, character) |
/**
Sets a direct server configuration to be inserted as the first server entry.
Uses fluent API pattern to allow method chaining.
If called multiple times, the last call wins.
Call before Open() to add a direct server URL.
Also updates default values for parameterized servers.
@param character Scheme (http/https), ? or empty to use default
@param character Hostname, ? or empty to use default
@param integer Port number, ? or 0 to use default
@param character Context path, ? or empty to use default
@param character Base path, ? or empty to use default
@return IOpenAPIServiceWriter Returns this instance for method chaining
*/
|
||
| OpenEdge.Web.DataObject.Writer.IOpenAPIServiceWriter UseBasicAuth (character) |
/**
Configures HTTP Basic Authentication as the security scheme.
This is used when client.login.model is 'basic', 'form', or 'container'.
Call before Open() to include security scheme in the generated spec.
Uses a default description.
@param character Realm name (e.g., from http.all.realm property)
@return IOpenAPIServiceWriter Returns this instance for method chaining
*/
|
||
| OpenEdge.Web.DataObject.Writer.IOpenAPIServiceWriter UseBasicAuth (character, character) |
/**
Configures HTTP Basic Authentication as the security scheme with custom description.
This is used when client.login.model is 'basic', 'form', or 'container'.
Call before Open() to include security scheme in the generated spec.
Throws an error if a different security scheme is already configured.
@param character Realm name (e.g., from http.all.realm property)
@param character Custom description for the scheme
@return IOpenAPIServiceWriter Returns this instance for method chaining
*/
|
||
| OpenEdge.Web.DataObject.Writer.IOpenAPIServiceWriter UseBearerAuth (character) |
/**
Configures Bearer token authentication as the security scheme.
This is used when client.login.model is 'sso', 'oauth2', or 'saml'.
Call before Open() to include security scheme in the generated spec.
Uses a default description.
@param character Bearer format (e.g., 'JWT', 'Client-Principal', 'SAML')
@return IOpenAPIServiceWriter Returns this instance for method chaining
*/
|
||
| OpenEdge.Web.DataObject.Writer.IOpenAPIServiceWriter UseBearerAuth (character, character) |
/**
Configures Bearer token authentication as the security scheme with custom description.
This is used when client.login.model is 'sso', 'oauth2', or 'saml'.
Call before Open() to include security scheme in the generated spec.
Throws an error if a different security scheme is already configured.
@param character Bearer format (e.g., 'JWT', 'Client-Principal', 'SAML')
@param character Custom description for the scheme
@return IOpenAPIServiceWriter Returns this instance for method chaining
*/
|
||
| Write (Object[]) |
/**
Writes service data to the OpenAPI document.
Public override to satisfy interface contract.
@param DataObjectService The service to write to the document
*/
|
||
| WriteAllJsonSchemas (DataObjectService) |
/** Writes all JSON schemas from a service's map schemas to the components/schemas section.
This ensures all defined schemas are available in the OpenAPI document, including those
referenced by other schemas via $ref. Calls WriteJsonSchema for each schema to reuse
the write logic.
@param DataObjectService The service containing the JSON schemas
*/
|
||
| Progress.Json.ObjectModel.JsonObject WriteDataset (handle) |
/**
Creates a JSON Schema representation of an ABL dataset.
Produces a nested object structure with properties for each buffer in the dataset.
@param handle A valid dataset handle
@return JsonObject The JSON Schema object representing the dataset structure
*/
|
||
| WriteDefaultFieldValue (handle, JsonObject) |
/* Writes the correctly-typed default value for a field
@param handle A valid buffer-field handle
@param JsonObject A valid JSON object representing the field */
|
||
| Progress.Json.ObjectModel.JsonObject WriteDefaultSchemas () |
/**
Create the default JSON object for schemas.
@return JsonObject The default schema object
*/
|
||
| Progress.Json.ObjectModel.JsonArray WriteDefaultServers () |
/**
Creates the default server configuration array for OpenAPI document.
Includes both absolute and relative path server configurations with
parameterized variables for scheme, host, port, context, and basePath.
Note: Direct server entries are added by ApplyUserContext() after this method runs.
@return JsonArray Array of server configuration objects
*/
|
||
| Progress.Json.ObjectModel.JsonObject WriteHeaders (MappedOperation) |
/**
Creates a headers object for an operation's response.
Generates schema definitions for all HTTP headers defined in the operation.
@param MappedOperation The operation containing header definitions
@return JsonObject Headers object with schema definitions, or unknown if no headers
*/
|
||
| Progress.Json.ObjectModel.JsonObject WriteInfo () |
/**
Creates the info section of the OpenAPI document.
Includes title, description, terms of service, and version information.
@return JsonObject The info object for the OpenAPI document
*/
|
||
| WriteJsonSchema (DataObjectService, character, JsonObject) |
/**
Writes a JSON Schema to the components/schemas section.
@param DataObjectService The service containing the schema
@param character The schema name
@param JsonObject The JSON Schema definition
*/
|
||
| WriteOperation (DataObjectService, MappedOperation) |
|
||
| WriteOperationSecurity (JsonObject, MappedOperation) |
/**
Adds security requirements to an operation based on its AccessControl roles.
If a security scheme is configured, references it with required roles.
If no scheme is configured, uses x-required-roles extension instead.
@param JsonObject The operation JSON object to add security to
@param MappedOperation The operation containing AccessControl role requirements
*/
|
||
| WriteSchema (DataObjectService, handle) |
/**
Writes a schema definition to the components/schemas section.
Handles datasets, buffers, and temp-tables by generating appropriate JSON Schema.
Note: For per-operation schemas, inline definitions are used within operations.
Service-level schemas use references via $ref to this components/schemas section.
This method is typically called during service initialization to populate shared schemas.
@param DataObjectService The service containing the schema
@param handle A valid dataset, buffer, or table handle
*/
|
||
| WriteSecuritySchemes (JsonObject) |
/**
Creates the security schemes section for the OpenAPI document.
Defines authentication mechanisms based on configuration (UseBasicAuth, UseBearerAuth).
Only adds securitySchemes property to components if a scheme is configured.
@param JsonObject The components object to conditionally add securitySchemes to
*/
|
||
| WriteService (DataObjectService) |
/**
Writes service metadata to the OpenAPI document.
Updates the info section with service description and version, and creates
a tag for grouping operations under this service.
@param DataObjectService The service to write metadata for
*/
|
||
| Progress.Json.ObjectModel.JsonObject WriteServiceRoot () |
/**
Creates the root OpenAPI document structure.
Initializes all required sections including openapi version, info, servers,
paths, components (with schemas), security, and tags.
@return JsonObject The root OpenAPI document object
*/
|
||
| Progress.Json.ObjectModel.JsonObject WriteTable (handle) |
/**
Creates a JSON Schema representation of an ABL temp-table or buffer.
Produces an array type with items containing all non-hidden fields as properties.
Identifies required fields based on unique indexes.
@param handle A valid buffer handle
@return JsonObject The JSON Schema object representing the table structure
*/
|
||
| WriteTag (character, character, JsonObject) |
/**
Adds or updates a tag in the OpenAPI document's tags array.
Tags are used to group operations and provide additional metadata.
@param character Tag name (must be unique)
@param character Tag description
@param JsonObject Optional external documentation object
*/
|
||
| WriteURI (URI) |
/**
Writes a URI to the output
@param URI The URI to write */
|
Constructor Summary
| Options | Name | Purpose | |
|---|---|---|---|
| OpenAPI30ServiceWriter () |
|
||
| OpenAPI30ServiceWriter () |
|
Property Summary
| Options | Name | Purpose | |
|---|---|---|---|
| OpenEdge.Core.SemanticVersion OPEN_API_VERSION |
|
Method Detail
AddNullableProperty (JsonObject)
|
||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
AddPropertyWithSchema (DataObjectService, JsonObject, character, character, character)
|
||||||||||||||||||||||||||||||||||||||||||
ApplyFieldFormat (JsonObject, character)
|
||||||||||||||||||||||||||||||||||||||||||
ApplyUserContext ()
|
||||||||||||||||||||||||||||||||||||||||||
Close ()
|
||||||||||||||||||||||||||||||||||||||||||
Progress.Json.ObjectModel.JsonObject CreateArrayFieldSchema (handle, character)
|
||||||||||||||||||||||||||||||||||||||||||
Progress.Json.ObjectModel.JsonObject CreateFieldSchema (handle, character)
|
||||||||||||||||||||||||||||||||||||||||||
CHARACTER FieldInfo (character, character)
|
||||||||||||||||||||||||||||||||||||||||||
OpenEdge.Security.Principal GetCurrentPrincipal ()
|
||||||||||||||||||||||||||||||||||||||||||
Progress.Json.ObjectModel.JsonObject GetJsonSchema (DataObjectService, character)
|
||||||||||||||||||||||||||||||||||||||||||
Progress.Json.ObjectModel.JsonObject GetPathJson (DataObjectService, character, MethodEnum)
|
||||||||||||||||||||||||||||||||||||||||||
OpenEdge.Web.DataObject.Writer.IOpenAPIServiceWriter IncludeRoleRequirements ()
|
||||||||||||||||||||||||||||||||||||||||||
LOGICAL IsOperationAuthorized (MappedOperation)
|
||||||||||||||||||||||||||||||||||||||||||
MarkRequiredField (JsonObject, character, character)
|
||||||||||||||||||||||||||||||||||||||||||
MarkRequiredFields (JsonObject, character)
|
||||||||||||||||||||||||||||||||||||||||||
Open ()
|
||||||||||||||||||||||||||||||||||||||||||
RemoveEmptyServices ()
|
||||||||||||||||||||||||||||||||||||||||||
CHARACTER ScrubPunctuation (character)
|
||||||||||||||||||||||||||||||||||||||||||
OpenEdge.Web.DataObject.Writer.IOpenAPIServiceWriter SetDocumentVersion (character)
|
||||||||||||||||||||||||||||||||||||||||||
OpenEdge.Web.DataObject.Writer.IOpenAPIServiceWriter SetServer (character, character, integer, character, character)
|
||||||||||||||||||||||||||||||||||||||||||
OpenEdge.Web.DataObject.Writer.IOpenAPIServiceWriter UseBasicAuth (character)
|
||||||||||||||||||||||||||||||||||||||||||
OpenEdge.Web.DataObject.Writer.IOpenAPIServiceWriter UseBasicAuth (character, character)
|
||||||||||||||||||||||||||||||||||||||||||
OpenEdge.Web.DataObject.Writer.IOpenAPIServiceWriter UseBearerAuth (character)
|
||||||||||||||||||||||||||||||||||||||||||
OpenEdge.Web.DataObject.Writer.IOpenAPIServiceWriter UseBearerAuth (character, character)
|
||||||||||||||||||||||||||||||||||||||||||
Write (Object[])
|
||||||||||||||||||||||||||||||||||||||||||
WriteAllJsonSchemas (DataObjectService)
|
||||||||||||||||||||||||||||||||||||||||||
Progress.Json.ObjectModel.JsonObject WriteDataset (handle)
|
||||||||||||||||||||||||||||||||||||||||||
WriteDefaultFieldValue (handle, JsonObject)
|
||||||||||||||||||||||||||||||||||||||||||
Progress.Json.ObjectModel.JsonObject WriteDefaultSchemas ()
|
||||||||||||||||||||||||||||||||||||||||||
Progress.Json.ObjectModel.JsonArray WriteDefaultServers ()
|
||||||||||||||||||||||||||||||||||||||||||
Progress.Json.ObjectModel.JsonObject WriteHeaders (MappedOperation)
|
||||||||||||||||||||||||||||||||||||||||||
Progress.Json.ObjectModel.JsonObject WriteInfo ()
|
||||||||||||||||||||||||||||||||||||||||||
WriteJsonSchema (DataObjectService, character, JsonObject)
|
||||||||||||||||||||||||||||||||||||||||||
WriteOperation (DataObjectService, MappedOperation)
|
||||||||||||||||||||||||||||||||||||||||||
WriteOperationSecurity (JsonObject, MappedOperation)
|
||||||||||||||||||||||||||||||||||||||||||
WriteSchema (DataObjectService, handle)
|
||||||||||||||||||||||||||||||||||||||||||
WriteSecuritySchemes (JsonObject)
|
||||||||||||||||||||||||||||||||||||||||||
WriteService (DataObjectService)
|
||||||||||||||||||||||||||||||||||||||||||
Progress.Json.ObjectModel.JsonObject WriteServiceRoot ()
|
||||||||||||||||||||||||||||||||||||||||||
Progress.Json.ObjectModel.JsonObject WriteTable (handle)
|
||||||||||||||||||||||||||||||||||||||||||
WriteTag (character, character, JsonObject)
|
||||||||||||||||||||||||||||||||||||||||||
WriteURI (URI)
|
||||||||||||||||||||||||||||||||||||||||||
Constructor Detail
STATIC OpenAPI30ServiceWriter () |
||||
|---|---|---|---|---|
OpenAPI30ServiceWriter () |
||||
Property Detail
OpenEdge.Core.SemanticVersion OPEN_API_VERSION
|
||||||||
|---|---|---|---|---|---|---|---|---|