openapi-tools / swagger-hal

Swagger extension to support the HAL JSON formatting

Swagger HAL Module

This module is intended to ensure correct documentation generated by Swagger when the Jackson HAL module is being used for generating HAL JSON output.

The Jackson HAL module allows for defining HAL properties by annotation.

@Resource
class Domain {
    @Link
    HALLink self;
    
    @EmbeddedResource
    RelatedResource resource;
}

However generating OpenAPI documentation using Swagger the OpenAPI document would not reflect the correct output.

...
  definitions:
    Domain:
      type: 'object'
      properties:
        self:
          $ref: '#/definitions/HALLink'
        resource:
          $ref: '#/definitions/RelatedResource'
...

Adding the Swagger HAL Module to the classpath the output will be correct.

...
  definitions:
    Domain:
      type: 'object'
      properties:
        _links:
          type: 'object'
          properties:
            self:
              $ref: '#/definitions/HALLink'
        _embedded:
          type: 'object'
          properties:
            resource:
              $ref: '#/definitions/RelatedResource'
...

Status

Module is considered production ready.

Usage

The Swagger module will be automatically discovered by Swagger when present in the classpath.

Caveat: Using the Swagger Maven Plugin

Note: Using the Open API Tools Swagger Maven plugin will also solve this issue.

The Swagger Maven Plugin manipulates the extensions of Swagger and does not call upwards in the ModelConverter chain. Therefor it is necessary to configure the Swagger HAL Module explicitly. The following illustrates the necessary configuration.

<plugin>
    <groupId>com.github.kongchen</groupId>
    <artifactId>swagger-maven-plugin</artifactId>
    <version>${swagger-maven-plugin.version}</version>
    <dependencies>
        <dependency>
            <groupId>io.openapitools.hal</groupId>
            <artifactId>swagger-hal</artifactId>
            <version>${swagger-hal.version}</version>
        </dependency>
    </dependencies>
    <configuration>
        <apiSources>
            <apiSource>
                <!-- add the model converter -->
                <modelConverters>
                    <modelConverter>io.openapi.tools.swagger.HALModelConverter</modelConverter>
                </modelConverters>
            </apiSource>
        </apiSources>
    </configuration>
    <executions>
        <execution>
            <phase>compile</phase>
            <goals>
                <goal>generate</goal>
            </goals>
        </execution>
    </executions>
</plugin>

swagger-hal's Issues

Migrate to Swagger 2.x

Migrate Swagger HAL support to Swagger 2.x to support OpenAPI 3.