-
-
Notifications
You must be signed in to change notification settings - Fork 582
specification extensions
The APIs.guru API collection defines and uses a number of OpenAPI specification extensions (known as vendor extensions in Swagger 2.0).
See also a list of these vendors with their own extensions documented.
See here for documentation generated from the official SEMOASA standard document.
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.
info:
x-origin:
- format: swagger
url: 'https://raw.githubusercontent.com/Mermade/bbcparse/master/iblApi/swagger.json'
version: '2.0'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.
- openapi
- swagger
- postman
- 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, and an x-apisguru-driver indicating which driver is to be used to update the API document (e.g. external, url, github, catalog, apisjson, blob, zip etc).
[
{
"url": "http://programmes.api.bbc.com/nitro/api",
"contentType": "application/json",
"converter": {
"url": "https://github.com/mermade/bbcparse",
"version": "1.2.0"
}
}
]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
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
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.
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.
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). Boolean
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. Boolean
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.
info:
x-logo:
backgroundColor: '#FFFFFF'
url: 'http://static.bbci.co.uk/tviplayer/1.101.2/img/navigation/iplayer_pink.svg'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.
"info": {
"x-apiClientRegistration": {
"url": "https://developer.bbc.co.uk/user/register"
}
}A property of the info object, x-apisguru-categories is an array of valid values from the list of APIs.guru categories.
Also a property of the info object, x-tags is an array of free-form keywords/tags applicable to the API.
Also a property of the info object, x-issues is an array of links to issues related to the API. In the APIs.guru collection, this property will only be present if the x-tags array contains the value helpWanted.
A property of the contact object, x-twitter is a string containing the API provider's Twitter account-name.