Documenting model metadata

[ivan-novakov]

Are there any best practices how to document model metadata such as hyperlinks, context, documentation? For example if I use HAL, the typical resource looks like this:

{
  "_links": {
    "self": { "href": "/employees/123456" }
  },
  "employeeId": 123456,
  "firstName": "Ivan",
  "lastName": "Novakov",
  "email": "ivan.novakov@company.com"
}

Now such parts like the _links section may be defined in the model definition, but they are not actually part of the model and sometimes the structure may be more complex and (what is worse) repeating across the different models.

Maybe there could be some general support for metadata in the Swagger specs, because most of the current JSON format/specifications use some kind of metadata, see:
http://sookocheff.com/posts/2014-03-11-on-choosing-a-hypermedia-format/

[webron]

There's currently no explicit support for http://json-schema.org/latest/json-schema-hypermedia.html. That said, you can still represent it as part of your model.

Regarding the repetition across different models, you can use model composition for it.

I'll mark the support for hypermedia as a proposal for the next spec version, but we'd need to see more public usage or user requests for it. It just doesn't seem that common at the moment.

[shamoons]

+1

[oytuntez]

One thing to note about this is probably overwriting model representations. As much as I am aware of, there isn't such thing. For example, "self" link would be different in different models and it would be amazing to specify this while linking to the model (path templating).

Edit
Perhaps: https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#composition-and-inheritance-polymorphism

[earth2marsh]

@webron The docs on composition and inheritance polymorphism that @oytuntez mentions is well written and succinct, but if it were possible to give an example, I'd be better positioned to prove that I understand what it declares. :) Should I file a separate issue with that request?

[webron]

@earth2marsh - apologies for the delay. Are the examples provided not enough? https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#models-with-composition and https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#models-with-polymorphism-support? I'd be happy to add clearer examples if needed, and yes please open a separate issue on the matter.

[handrews]

No further response since 2015, closing.