-
-
Notifications
You must be signed in to change notification settings - Fork 570
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.