OpenAPI Extensions Documentation
Scroll down for schema examples. Select a format for examples from the tabs above or the mobile navigation menu.
This documentation was automatically generated from a v0.1.0 Semoasa document.
Semoasa is a machine-readable format for extensions to Swagger/OpenAPI 2.0 and 3.0 specifications.
guru.apis
Provider: APIs.guru
x-apiClientRegistration
x-apiClientRegistration example
{
"url": "https://developer.bbc.co.uk/user/register"
}
url: 'https://developer.bbc.co.uk/user/register'
A link to a sign-up page for the API.
A property of the info object, x-apiClientRegistration includes a URL-formatted property url containing the URL to the resource where developers can register to authenticate with the API.
APIs.guru OpenAPI Directory Wiki
Property | Type | Required | Description |
---|---|---|---|
url | string(uri-ref) | true | No description |
In the OpenAPI specification v2.0, this extension can be used as follows:
Object | Description |
---|---|
InfoObject | The object provides metadata about the API. The metadata can be used by the clients if needed, and can be presented in editing or documentation generation tools for convenience. |
In the OpenAPI specification v3.x, this extension can be used as follows:
Object | Description |
---|---|
InfoObject | The object provides metadata about the API. The metadata can be used by the clients if needed, and can be presented in editing or documentation generation tools for convenience. |
x-apisguru-categories
x-apisguru-categories example
[
"string"
]
- string
A property of the info object, x-apisguru-categories
is an array of valid values from the list of APIs.guru categories.
APIs.guru OpenAPI Directory Wiki
Property | Type | Required | Description |
---|---|---|---|
anonymous | [string] | false | No description |
In the OpenAPI specification v2.0, this extension can be used as follows:
Object | Description |
---|---|
InfoObject | The object provides metadata about the API. The metadata can be used by the clients if needed, and can be presented in editing or documentation generation tools for convenience. |
In the OpenAPI specification v3.x, this extension can be used as follows:
Object | Description |
---|---|
InfoObject | The object provides metadata about the API. The metadata can be used by the clients if needed, and can be presented in editing or documentation generation tools for convenience. |
x-description-language
x-description-language example
"string"
string
An ISO-639 two-character language code to identify the natural language used in descriptions, summaries and titles. This can be used as an input to translating these items.
Property | Type | Required | Description |
---|---|---|---|
simple | string | false | No description |
In the OpenAPI specification v2.0, this extension can be used as follows:
Object | Description |
---|---|
InfoObject | The object provides metadata about the API. The metadata can be used by the clients if needed, and can be presented in editing or documentation generation tools for convenience. |
In the OpenAPI specification v3.x, this extension can be used as follows:
Object | Description |
---|---|
InfoObject | The object provides metadata about the API. The metadata can be used by the clients if needed, and can be presented in editing or documentation generation tools for convenience. |
x-hasEquivalentPaths
x-hasEquivalentPaths example
true
true
A property of the root
object, x-hasEquivalentPaths
indicates the source specification has multiple paths which map to the same OpenAPI path (possibly disambiguated with HTML fragment identifiers or differently named path parameters).
Property | Type | Required | Description |
---|---|---|---|
simple | boolean | false | No description |
In the OpenAPI specification v2.0, this extension can be used as follows:
Object | Description |
---|---|
SwaggerObject | Description not found |
In the OpenAPI specification v3.x, this extension can be used as follows:
Object | Description |
---|---|
OpenAPIObject | Description not found |
x-logo
x-logo example
{
"url": "string",
"backgroundColor": "string"
}
url: string
backgroundColor: string
A logo for the API.
A property of the info
object, the x-logo
structure holds an absolute URL to the API logo and an optional background colour in HTML hex notation.
APIs.guru OpenAPI Directory Wiki
Property | Type | Required | Description |
---|---|---|---|
url | string(uri-ref) | true | No description |
backgroundColor | string | false | No description |
In the OpenAPI specification v2.0, this extension can be used as follows:
Object | Description |
---|---|
InfoObject | The object provides metadata about the API. The metadata can be used by the clients if needed, and can be presented in editing or documentation generation tools for convenience. |
In the OpenAPI specification v3.x, this extension can be used as follows:
Object | Description |
---|---|
InfoObject | The object provides metadata about the API. The metadata can be used by the clients if needed, and can be presented in editing or documentation generation tools for convenience. |
x-origin
x-origin example
[
{
"url": "http://programmes.api.bbc.com/nitro/api",
"contentType": "application/json",
"converter": {
"url": "https://github.com/mermade/bbcparse",
"version": "1.2.0"
}
},
{
"format": "swagger",
"url": "https://raw.githubusercontent.com/Mermade/bbcparse/master/iblApi/swagger.json",
"version": "2.0"
}
]
- url: 'http://programmes.api.bbc.com/nitro/api'
contentType: application/json
converter:
url: 'https://github.com/mermade/bbcparse'
version: 1.2.0
- format: swagger
url: >-
https://raw.githubusercontent.com/Mermade/bbcparse/master/iblApi/swagger.json
version: '2.0'
A property of the info
object, the x-origin
structure is used to document the source and format of an API in the collection. It is used to round-trip the process of keeping the APIs updated.
Please note, if you include an x-origin extension within your API definition APIs.guru will then append to this array if it exists, allowing an audit trail of the source(s) of an API definition. Valid values for format
- swagger
- api_blueprint
- raml
In your own x-origin
entries you may alternatively use a contentType property instead of a format property. The version property is then optional.
You may also specify the converter and version used.
Property | Type | Required | Description |
---|---|---|---|
anonymous | [object] | false | No description |
» url | string(uri-ref) | true | No description |
» format | string | false | No description |
» version | string | false | No description |
» contentType | string | false | No description |
» converter | object | false | No description |
»» url | string(uri-ref) | false | No description |
»» version | string | false | No description |
In the OpenAPI specification v2.0, this extension can be used as follows:
Object | Description |
---|---|
InfoObject | The object provides metadata about the API. The metadata can be used by the clients if needed, and can be presented in editing or documentation generation tools for convenience. |
In the OpenAPI specification v3.x, this extension can be used as follows:
Object | Description |
---|---|
InfoObject | The object provides metadata about the API. The metadata can be used by the clients if needed, and can be presented in editing or documentation generation tools for convenience. |
x-preferred
x-preferred example
"string"
string
A property of the info
object, x-preferred
is a Boolean property which distinguishes between multiple versions of the same API. Where the x-providerName
and x-serviceName
are the same, only one definition should be marked x-preferred: true
. This helps users of the APIs.guru collection organise and display the APIs.
Property | Type | Required | Description |
---|---|---|---|
simple | string | false | No description |
In the OpenAPI specification v2.0, this extension can be used as follows:
Object | Description |
---|---|
InfoObject | The object provides metadata about the API. The metadata can be used by the clients if needed, and can be presented in editing or documentation generation tools for convenience. |
In the OpenAPI specification v3.x, this extension can be used as follows:
Object | Description |
---|---|
InfoObject | The object provides metadata about the API. The metadata can be used by the clients if needed, and can be presented in editing or documentation generation tools for convenience. |
x-providerName
x-providerName example
"string"
string
A property of the info
object, x-providerName
is used to identify the domain of the API host. It is added automatically by APIs.guru
Property | Type | Required | Description |
---|---|---|---|
simple | string | false | No description |
In the OpenAPI specification v2.0, this extension can be used as follows:
Object | Description |
---|---|
InfoObject | The object provides metadata about the API. The metadata can be used by the clients if needed, and can be presented in editing or documentation generation tools for convenience. |
In the OpenAPI specification v3.x, this extension can be used as follows:
Object | Description |
---|---|
InfoObject | The object provides metadata about the API. The metadata can be used by the clients if needed, and can be presented in editing or documentation generation tools for convenience. |
x-serviceName
x-serviceName example
"string"
string
A property of the info
object, x-serviceName
is used to distinguish APIs which are served from the same domain. It may be the subdomain if the API uses one. It is added automatically by APIs.guru
Property | Type | Required | Description |
---|---|---|---|
simple | string | false | No description |
In the OpenAPI specification v2.0, this extension can be used as follows:
Object | Description |
---|---|
InfoObject | The object provides metadata about the API. The metadata can be used by the clients if needed, and can be presented in editing or documentation generation tools for convenience. |
In the OpenAPI specification v3.x, this extension can be used as follows:
Object | Description |
---|---|
InfoObject | The object provides metadata about the API. The metadata can be used by the clients if needed, and can be presented in editing or documentation generation tools for convenience. |
x-tags
x-tags example
[
"string"
]
- string
Also a property of the info
object, x-tags
is an array of free-form keywords/tags applicable to the API.
Property | Type | Required | Description |
---|---|---|---|
anonymous | [string] | false | No description |
In the OpenAPI specification v2.0, this extension can be used as follows:
Object | Description |
---|---|
InfoObject | The object provides metadata about the API. The metadata can be used by the clients if needed, and can be presented in editing or documentation generation tools for convenience. |
In the OpenAPI specification v3.x, this extension can be used as follows:
Object | Description |
---|---|
InfoObject | The object provides metadata about the API. The metadata can be used by the clients if needed, and can be presented in editing or documentation generation tools for convenience. |
x-unofficialSpec
x-unofficialSpec example
true
true
A property of the info
object, x-unofficialSpec
indicates the definition is produced by a third-party, either manually, by scraping existing documentation or converting a proprietary/undocumented format.
Property | Type | Required | Description |
---|---|---|---|
simple | boolean | false | No description |
In the OpenAPI specification v2.0, this extension can be used as follows:
Object | Description |
---|---|
InfoObject | The object provides metadata about the API. The metadata can be used by the clients if needed, and can be presented in editing or documentation generation tools for convenience. |
In the OpenAPI specification v3.x, this extension can be used as follows:
Object | Description |
---|---|
InfoObject | The object provides metadata about the API. The metadata can be used by the clients if needed, and can be presented in editing or documentation generation tools for convenience. |