Openapi-specification: Add more details in the "Contact" Object

[elharony]

For most people, email and url may be enough, but others - me, in today's case - need more info like jobTitle/position, phone, companyName, and companyUrl. This may be important if we write API Specification for another company.

[MikeRalphson]

As you say, for most people (based also on issues here) the existing fields in the contact object are probably sufficient. As per the specification:

This object MAY be extended with Specification Extensions

so you can define and use such fields as x-job-title, x-phone within this object.

[elharony]

Thanks, @MikeRalphson for taking the time to check my issue & mentioning the x-property to extend the object.

What I really wanted was the phone with a tel: action for emergency stuff to be added to the specification, other properties were more of a suggestion to additional properties if anybody needed them, will be recognizable & available in OAS.

It's my first time to contribute at OAS, not really sure about the process to introduce something new (i.e. Adding phone, with tel: action in this case).

[MikeRalphson]

Check out DEVELOPMENT.md for an overview of the change processes. Bear in mind not all suggested changes, even if practical, will make it into the specification. Every new field and feature has a cost for those implementing the specification in tooling.

Basically the process would be to see if the issue gains support from the wider TDC, and then to take it to a PR against the spec itself. More complex changes might use the 'proposals' process.

[elharony]

@MikeRalphson Many thanks for explaining this to me. It's very clear now! 👍

[darrelmiller]

@elharony Also, take a look at http://apisjson.org/ as it provides the ability to add a lot more information to an API. The apisjson spec can be used in combination with OpenAPI descriptions.

[elharony]

@darrelmiller Thank you, Darrel. Will give it a try!