[OFBIZ-12516] Add functionality to configure and return additional response status codes for an operation

• Type: Sub-task
• Status: Open
• Priority: Major
• Resolution: Unresolved
• Affects Version/s: Upcoming Branch
• Component/s: rest-api
• Assignee: Michael Brohl
• Reporter: Michael Brohl
• Created: 22/Jan/22 14:57
• Updated: 22/Jan/22 15:12

Description

Currently, the rest-api plugin has a fixed set of possible response status codes which are published through the OpenAPI documentation (Swagger UI). The base set makes sense for every request as I see it.

For the implementation if individual business cases, additional additional response status codes are needed sometimes, which also should be published through the OpenAPI documentation.

We have enhanced the res-api code to handle this as follows.

On operation level, a comma separated list of additional response codes can be configured. They will be added to the base list of codes and published.

Example:

<?xml version="1.0" encoding="UTF-8"?>
<api publish="false" description="Product Information Management API" displayName="PIM API" name="PIM" 
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="http://ofbiz.apache.org/dtds/rest-api.xsd">
    <resource description="APIs related to Product and related entities" displayName="Product Resource" name="Product Resource" 
        path="/products" auth="true" >
        <!-- this will configure the additional response codes 201/202 -->
        <operation verb="post" description="Creates a product." mainAction="CREATE" addApiResponses="201,202">
            <service name="createProduct"/>
        </operation>
    </resource>
</api>

Additionally, we have enhanced the functionality to enable services to control which response status code will be returned after the service has finished. This will be enabled with an additional service attribute "httpResponseStatus" (optional or non-optional). If this is set in the result map of the service, it's value will be mapped against the standard response codes and returned instead of the default code (both in the request and the resulting JSON.

This is currently in development/test phase in a custom project, I will soon provide a PR for it.