OpenAPI Documents (since 2.19)
General
In addition to the well-known WSDL and WADL documents, the PTV xServer also provides OpenAPI documents for the Swagger 2.0
specification since version 2.19. These JSON
JSON (JavaScript Object Notation) is an open standard format for which human-readable text is used to transmit information consisting of attribute–value pairs. It is the first-address data format used for asynchronous browser/server communication (AJAX). and YAML documents are available for all versioned APIs starting with 2.19 and
for the head and experimental API. The Services Page includes links to these
documents if an endpoint is hosted for this API.
Each OpenAPI document covers both the JSON API (over HTTP Post) and the REST REST (Representational State Transfer) represents a World Wide Web paradigm, consisting of constraints to the design of components which results in a better performance and maintainability. API (over HTTP Get).
- not referenced definitions
- properties with parallel
$refanddescriptionentries
Jobs
Jobs can be used with OpenAPI as usual. However, due to the missing namespace support the managing operations
watchJob, stopJob and deleteJob
are only available in xRuntime and not in specific services.
Vendor Extensions
To improve generation of clients the OpenAPI Documents are enriched by some vendor extensions like x-ms-parameter-grouping,
x-discriminator-value, x-ms-discriminator-value and x-ms-enum.
x-ms-paths was used to support different content types of the Map Tile API. Starting with 2.35 this has been
replaced by an alternative solution to better support OpenAPI Generator.
Compatibility
Generated clients based on an OpenAPI document for a specific API version (e.g. 2.19) will continue to work for future xServer releases (e.g. 2.20.1, 2.21.0, ...) if that API version is hosted. How previous API versions can be hosted is described under Services Configuration.
For OpenAPI documents of head or experimental APIs the restrictions of those APIs apply as described in the Versioning-Guidelines. Therefore we recommend to use the versioned API.
Schema names or operation IDs might change between API versions to mitigate the missing namespace support in OpenAPI. Thus, if you update your client to a new API version, you might have to adjust your source code.