Upgrade to Swagger 3

To upgrade from brXM 15.x to 16.y, update the API documentation for any Plain JAX-RS Services in your implementation project from Swagger v2 to v3.

Bloomreach Content supports Plain JAX-RS Services with default API documentation based on Swagger. For details, see Generating API Documentation in Swagger Format.

In Swagger v3, the OpenAPI endpoint names have changed. The endpoints are now named openapi.json and openapi.yaml instead of swagger.json and swagger.yaml.

Update Bean Configuration

Swagger v3 removes the default swaggerBeanConfig bean. brXM 16 introduces 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>
copy

If your implementation project does not override the swaggerBeanConfig bean, no action is required.

To use a custom bean instead of the default, redefine your project's swaggerBeanConfig bean as hstOpenApiBeanConfig. The following example demonstrates how to override the bean. This configuration is based on 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>
copy