{"id":21684681,"url":"https://github.com/openapi-tools/swagger-hal","last_synced_at":"2025-04-12T07:51:49.437Z","repository":{"id":27219755,"uuid":"102495451","full_name":"openapi-tools/swagger-hal","owner":"openapi-tools","description":"Swagger extension to support the HAL JSON formatting","archived":false,"fork":false,"pushed_at":"2022-04-05T16:37:56.000Z","size":51,"stargazers_count":12,"open_issues_count":2,"forks_count":2,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-03-26T03:04:59.540Z","etag":null,"topics":["hal-json","hal-json-openapi-formatter","hateoas","openapi-hal-formatter","openapi-hal-formatter-maven-plugin"],"latest_commit_sha":null,"homepage":null,"language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/openapi-tools.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-09-05T15:01:17.000Z","updated_at":"2025-02-20T13:33:00.000Z","dependencies_parsed_at":"2022-07-27T09:22:24.314Z","dependency_job_id":null,"html_url":"https://github.com/openapi-tools/swagger-hal","commit_stats":null,"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openapi-tools%2Fswagger-hal","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openapi-tools%2Fswagger-hal/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openapi-tools%2Fswagger-hal/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openapi-tools%2Fswagger-hal/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/openapi-tools","download_url":"https://codeload.github.com/openapi-tools/swagger-hal/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248537009,"owners_count":21120690,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["hal-json","hal-json-openapi-formatter","hateoas","openapi-hal-formatter","openapi-hal-formatter-maven-plugin"],"created_at":"2024-11-25T16:16:45.926Z","updated_at":"2025-04-12T07:51:49.412Z","avatar_url":"https://github.com/openapi-tools.png","language":"Java","readme":"# Swagger HAL Module\n\nThis module is intended to ensure correct documentation generated by Swagger when\nthe [Jackson HAL module](https://github.com/openapi-tools/jackson-dataformat-hal) is\nbeing used for generating [HAL JSON](http://tools.ietf.org/html/draft-kelly-json-hal)\noutput. \n\nThe [Jackson HAL module](https://github.com/openapi-tools/jackson-dataformat-hal) allows\nfor defining HAL properties by annotation.\n\n```java\n@Resource\nclass Domain {\n    @Link\n    HALLink self;\n    \n    @EmbeddedResource\n    RelatedResource resource;\n}\n```\n\nHowever generating OpenAPI documentation using Swagger the OpenAPI document\nwould not reflect the correct output.\n\n```yaml\n...\n  definitions:\n    Domain:\n      type: 'object'\n      properties:\n        self:\n          $ref: '#/definitions/HALLink'\n        resource:\n          $ref: '#/definitions/RelatedResource'\n...\n```\n\nAdding the Swagger HAL Module to the classpath the output will be correct.\n\n```yaml\n...\n  definitions:\n    Domain:\n      type: 'object'\n      properties:\n        _links:\n          type: 'object'\n          properties:\n            self:\n              $ref: '#/definitions/HALLink'\n        _embedded:\n          type: 'object'\n          properties:\n            resource:\n              $ref: '#/definitions/RelatedResource'\n...\n```\n\n# Status\n\nModule is considered production ready.\n\n[![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/)\n[![Javadoc](https://javadoc.io/badge/io.openapitools.hal/swagger-hal/badge.svg)](https://www.javadoc.io/doc/io.openapitools.hal/swagger-hal)\n[![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)\n\n# Usage\n\nThe Swagger module will be automatically discovered by Swagger when present in the classpath.\n\n## Caveat: Using the Swagger Maven Plugin\n\nNote: Using the [Open API Tools Swagger Maven plugin](https://github.com/openapi-tools/swagger-maven-plugin) will also solve this issue.\n\nThe Swagger Maven Plugin manipulates the extensions of Swagger and does not\ncall upwards in the ModelConverter chain. Therefor it is necessary to configure\nthe Swagger HAL Module explicitly. The following illustrates the necessary configuration.\n\n```xml\n\u003cplugin\u003e\n    \u003cgroupId\u003ecom.github.kongchen\u003c/groupId\u003e\n    \u003cartifactId\u003eswagger-maven-plugin\u003c/artifactId\u003e\n    \u003cversion\u003e${swagger-maven-plugin.version}\u003c/version\u003e\n    \u003cdependencies\u003e\n        \u003cdependency\u003e\n            \u003cgroupId\u003eio.openapitools.hal\u003c/groupId\u003e\n            \u003cartifactId\u003eswagger-hal\u003c/artifactId\u003e\n            \u003cversion\u003e${swagger-hal.version}\u003c/version\u003e\n        \u003c/dependency\u003e\n    \u003c/dependencies\u003e\n    \u003cconfiguration\u003e\n        \u003capiSources\u003e\n            \u003capiSource\u003e\n                \u003c!-- add the model converter --\u003e\n                \u003cmodelConverters\u003e\n                    \u003cmodelConverter\u003eio.openapi.tools.swagger.HALModelConverter\u003c/modelConverter\u003e\n                \u003c/modelConverters\u003e\n            \u003c/apiSource\u003e\n        \u003c/apiSources\u003e\n    \u003c/configuration\u003e\n    \u003cexecutions\u003e\n        \u003cexecution\u003e\n            \u003cphase\u003ecompile\u003c/phase\u003e\n            \u003cgoals\u003e\n                \u003cgoal\u003egenerate\u003c/goal\u003e\n            \u003c/goals\u003e\n        \u003c/execution\u003e\n    \u003c/executions\u003e\n\u003c/plugin\u003e\n```\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopenapi-tools%2Fswagger-hal","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fopenapi-tools%2Fswagger-hal","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopenapi-tools%2Fswagger-hal/lists"}