Upgrade to Swagger 3

Upgrade API documentation for any Plain JAX-RS Services in your implementation project from Swagger v2 to v3 to upgrade from Bloomreach Experience Manager 15.x to 16.y.

The support for Plain JAX-RS Services includes a default API documentation based on Swagger, see “Generating API Documentation in Swagger Format” in RESTful API Support - Plain JAX-RS Services.

The openAPI endpoint naming changed from swagger.json/swagger.yaml to openapi.json/openapi.yaml.

Update Bean Configuration

In Swagger v3, the default bean swaggerBeanConfig is not available anymore, therefore brXM 16 provides a new default bean for openAPI configuration:

<bean id="hstOpenApiBeanConfig" class="io.swagger.v3.oas.integration.SwaggerConfiguration">
        <property name="openAPI">
            <bean class="io.swagger.v3.oas.models.OpenAPI">
                <property name="info">
                    <bean class="io.swagger.v3.oas.models.info.Info">
                        <property name="title" value="Open API" />
                        <property name="version" value="v1" />
                        <property name="description" value="Bloomreach site toolkit JAX-RS" />
                    </bean>
                </property>
            </bean>
        </property>
    </bean>

If you implementation project does not override the swaggerBeanConfig then this should not affect you.

To use a custom bean instead of the above default bean, your implementation project must re-define the swaggerBeanConfig bean by renaming it to hstOpenApiBeanConfig. The example presented below is for the overriding the bean and is taken from the Test Suite package and can be used as a reference:

 <bean id="hstOpenApiBeanConfig" class="io.swagger.v3.oas.integration.SwaggerConfiguration">
        <property name="resourcePackages" value="org.hippoecm.hst.demo.jaxrs.services" />
        <property name="cacheTTL" value="0"/>
        <property name="openAPI">
            <bean class="io.swagger.v3.oas.models.OpenAPI">
                <property name="info">
                    <bean class="io.swagger.v3.oas.models.info.Info">
                        <property name="title" value="TestSuite REST API Examples" />
                        <property name="version" value="1.0" />
                        <property name="description" value="Provides TestSuite Content REST Services" />
                        <property name="termsOfService" value="http://www.example.com/terms-of-services.html" />
                        <property name="license">
                            <bean class="io.swagger.v3.oas.models.info.License">
                                <property name="name" value="Apache License, Version 2.0" />
                                <property name="url" value="https://www.apache.org/licenses/LICENSE-2.0" />
                            </bean>
                        </property>
                        <property name="contact">
                            <bean class="io.swagger.v3.oas.models.info.Contact">
                                <property name="email" value="[email protected]" />
                            </bean>
                        </property>
                    </bean>
                </property>
            </bean>
        </property>
    </bean>