added language section

[fehguy]

Fixes #70

[darrelmiller]

Perhaps we could reference a spec like http://tools.ietf.org/html/rfc1766 to define the valid values of the language property.

[ePaul]

Hmm, why not simply a map of links?

languages:
  current: en-us
  supportedLanguages:
    es: ./openapi.yaml?lang=es
    en-us: ./openapi.yaml?lang=en-us

Is this trying to avoid mentioning the own file-name?

[fehguy]

many use the header, so you can't describe it like such. I'll see if we can use a filename optionally.

[webron]

Perhaps this should move under the Info Object?

Regardless, I don't think this answers #70. It seems to talk about the API data, not the spec itself and its descriptions.

Not sure this should make it in, seems a bit fringe (unless I don't follow the use case).

[fehguy]

@OAI/tdc looking into this more, I'm going to propose we close it and don't merge. If that's fine, please reject this PR.

[webron]

👎

[jharmn]

I worry about confusion between language support in the API vs in the documentation.

For example, there are only certain languages supported in some APIs (where localized content is provided), but the docs might only be in English (http://developer.uship.com is a great example of this, albeit hard to look at their docs). Additionally, it would need to made clear how to change that APIs language (i.e. Content-Language header).

Even if we were to include this, I would rename it to something like documentationLanguage to disambiguate between API functionality and documentation-specific functionality.

IMO there is a bigger discussion about documentation-specifics leaking into the spec, vs API contract (which is a way higher priority).

I'm 👎 on this as it stands.

[fehguy]

I believe this needs more thought. Closing per feedback.

[earth2marsh]

👎

[gioppoluca]

The need coming from the #70 issue is do describe the language used in the data returned by the API.
That is useful in many cross border projects where a single API catalogue could return content from different countries and there is the need to know in which language is the content.
Obviously there also could be the need to declare the language of the description of the API, but that is another issue from the #70 and the two languages could be theoretically be different