Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

added language section #639

Closed
wants to merge 1 commit into from
Closed

added language section #639

wants to merge 1 commit into from

Conversation

fehguy
Copy link
Contributor

@fehguy fehguy commented Apr 8, 2016

Fixes #70

@darrelmiller
Copy link
Member

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

type: string
enum:
- en-us
- es
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

@webron
Copy link
Member

webron commented Apr 11, 2016

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
Copy link
Contributor Author

fehguy commented Apr 11, 2016

@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
Copy link
Member

webron commented Apr 12, 2016

👎

@jharmn
Copy link
Contributor

jharmn commented Apr 13, 2016

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
Copy link
Contributor Author

fehguy commented Apr 14, 2016

I believe this needs more thought. Closing per feedback.

@fehguy fehguy closed this Apr 14, 2016
@earth2marsh
Copy link
Member

👎

@gioppoluca
Copy link

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

7 participants