Support for HAL (Hypermedia Application Language) about swagger-php HOT 11 CLOSED

@pietervogelaar could you elaborate in detail the request? I am familiar with HAL however I am not clear with regards to what you require from Swagger to support it.

from swagger-php.

At the moment a property in a model can have multiple models. For example a user can have multiple contacts.

The response in JSON for a user will be:

{
    "id": "matthew",
    "name": "Matthew Weier O'Phinney",
    "contacts": [
       {
            "id": "mac_nibblet",
            "name": "Antoine Hedgecock"
      }, 
      {
          "id": "spiffyjr",
          "name": "Kyle Spraggs"
      }
   ]
}

But for HAL the response below is desired:

{
    "_links": {
        "self": {
            "href": "http://example.org/api/user/matthew"
        }
    }
    "id": "matthew",
    "name": "Matthew Weier O'Phinney",
    "_embedded": {
        "contacts": [
            {
                "_links": {
                    "self": {
                        "href": "http://example.org/api/user/mac_nibblet"
                    }
                },
                "id": "mac_nibblet",
                "name": "Antoine Hedgecock"
            },
            {
                "_links": {
                    "self": {
                        "href": "http://example.org/api/user/spiffyjr"
                    }
                },
                "id": "spiffyjr",
                "name": "Kyle Spraggs"
            }
        ],
        "website": {
            "_links": {
                "self": {
                    "href": "http://example.org/api/locations/mwop"
                }
            },
            "id": "mwop",
            "url": "http://www.mwop.net"
        },
    }
}

I think the annotations can stay the same, but the swagger bin should have a flag "hal_enabled" or something. So that child models will be enclosed in a "_embedded" key.

The _links key requires some annotation I think.

from swagger-php.

I agree, we would really need to get some support for JSON HAL into Swagger in order to be able to show the expected response in a correct way.

from swagger-php.

any progress on this?

from swagger-php.

Hi, folks! How are you? We also need this support in a project, does anyone have some new on this issue? Thank you, very much!

from swagger-php.

👍

from swagger-php.

+1

I am also struggling to figure out how to support JSON-API schema as well, seems support for arbitrarily nested attribute objects is not straight forward unless I'm missing something.

i.e. how would I support this response:

{
  "data": [
    {
      "id": 1,
      "type": "pet",
      "attributes": {
        "id": 1,
        "name": "Dog"
      },
      "links": {
        "count": "/pets/1/count"
      }
    }
  ]
}

from swagger-php.

@nnnnathann got similar issue with nested object. I've just created a class for each object in JSON and marked them in phpdoc annotations. Example based on your JSON:

class Pet {
  /** @var PetAttrs */
  var $attributes;
}

class PetAttrs {
  var $id;
  var $name;
}

from swagger-php.

@adambro @nnnnathann for nested definition, you can check this out. 😃

from swagger-php.

+1 for HAL support.

from swagger-php.

HAL support is outside the scope of the swagger-php project.

Feel free to experiment and create a swagger-php plugin, i'll gladly add that to the related projects page

from swagger-php.