Skip to content

added language section #639

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.

Sign up for GitHub

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

Closed
wants to merge 1 commit into from
Closed

added language section #639

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 25 additions & 0 deletions versions/3.0.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -108,6 +108,7 @@ Field Name | Type | Description
---|:---:|---
<a name="oasSwagger"></a>swagger | `string` | **Required.** Specifies the OpenAPI Specification version being used. It can be used by the Swagger UI and other clients to interpret the API listing. The value MUST be `"2.0"`.
<a name="oasInfo"></a>info | [Info Object](#infoObject) | **Required.** Provides metadata about the API. The metadata can be used by the clients if needed.
<a name="oasLanguages"></a>languages | [Languages Object](#languagesObject) | Provides information about the language that the OAS document supports, and how to select alternate formats of the document
<a name="oasHost"></a>host | `string` | The host (name or ip) serving the API. This MUST be the host only and does not include the scheme nor sub-paths. It MAY include a port. If the `host` is not included, the host serving the documentation is to be used (including the port). The `host` does not support [path templating](#pathTemplating).
<a name="oasBasePath"></a>basePath | `string` | The base path on which the API is served, which is relative to the [`host`](#oasHost). If it is not included, the API is served directly under the `host`. The value MUST start with a leading slash (`/`). The `basePath` does not support [path templating](#pathTemplating).
<a name="oasSchemes"></a>schemes | [`string`] | The transfer protocol of the API. Values MUST be from the list: `"http"`, `"https"`, `"ws"`, `"wss"`. If the `schemes` is not included, the default scheme to be used is the one used to access the OpenAPI definition itself.
Expand Down Expand Up @@ -189,6 +190,30 @@ Contact information for the exposed API.

##### Fixed Fields

Field Name | Type | Description
---|:---:|---
<a name="languagesCurrent"></a>current | `string` | The language code for the current document.
<a name="supportedLanguages"></a>supportedLanguages | [Parameter Object] | A parameter object of type `in: header` or `in: query` used to describe how to fetch the OAS document in the language allowed by the `enum`

Example:
```yaml
languages:
current: en-us
supportedLanguages:
in: query
name: lang
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.

```

#### <a name="contactObject"></a>Contact Object

Contact information for the exposed API.

##### Fixed Fields

Field Name | Type | Description
---|:---:|---
<a name="contactName"></a>name | `string` | The identifying name of the contact person/organization.
Expand Down