https://github.com/openapi-tools/swagger-hal

Swagger extension to support the HAL JSON formatting
https://github.com/openapi-tools/swagger-hal

hal-json hal-json-openapi-formatter hateoas openapi-hal-formatter openapi-hal-formatter-maven-plugin

Last synced: 6 months ago
JSON representation

Swagger extension to support the HAL JSON formatting

• Host: GitHub
• URL: https://github.com/openapi-tools/swagger-hal
• Owner: openapi-tools
• License: mit
• Created: 2017-09-05T15:01:17.000Z (about 8 years ago)
• Default Branch: main
• Last Pushed: 2022-04-05T16:37:56.000Z (over 3 years ago)
• Last Synced: 2025-03-26T03:04:59.540Z (6 months ago)
• Topics: hal-json, hal-json-openapi-formatter, hateoas, openapi-hal-formatter, openapi-hal-formatter-maven-plugin
• Language: Java
• Size: 49.8 KB
• Stars: 12
• Watchers: 3
• Forks: 2
• Open Issues: 2
• Metadata Files:
  • Readme: README.md
  • License: LICENSE

Awesome Lists containing this project

README

          
# Swagger HAL Module

This module is intended to ensure correct documentation generated by Swagger when

the [Jackson HAL module](https://github.com/openapi-tools/jackson-dataformat-hal) is

being used for generating [HAL JSON](http://tools.ietf.org/html/draft-kelly-json-hal)

output. 

The [Jackson HAL module](https://github.com/openapi-tools/jackson-dataformat-hal) allows

for defining HAL properties by annotation.

```java

@Resource

class Domain {

    @Link

    HALLink self;

    

    @EmbeddedResource

    RelatedResource resource;

}

```

However generating OpenAPI documentation using Swagger the OpenAPI document

would not reflect the correct output.

```yaml

...

  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.

```yaml

...

  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.

[![Maven Central](https://maven-badges.herokuapp.com/maven-central/io.openapitools.hal/swagger-hal/badge.svg)](https://maven-badges.herokuapp.com/maven-central/io.openapitools.hal/swagger-hal/)

[![Javadoc](https://javadoc.io/badge/io.openapitools.hal/swagger-hal/badge.svg)](https://www.javadoc.io/doc/io.openapitools.hal/swagger-hal)

[![CI](https://github.com/openapi-tools/swagger-hal/actions/workflows/ci.yaml/badge.svg)](https://github.com/openapi-tools/swagger-hal/actions/workflows/ci.yaml)

# 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](https://github.com/openapi-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.

```xml

    com.github.kongchen

    swagger-maven-plugin

    ${swagger-maven-plugin.version}

    

        

            io.openapitools.hal

            swagger-hal

            ${swagger-hal.version}

        

    

    

        

            

                

                

                    io.openapi.tools.swagger.HALModelConverter

                

            

        

    

    

        

            compile

            

                generate

            

        

    

```