OpenAPI

The OpenAPI (OAS) specification 2.0 (fka Swagger 2.0 specification) is the industry standard for defining REST APIs. The OAS specification defines a set of files required to describe an API. These files can then be used by the Swagger-UI project to display the API and Swagger-codegen to generate clients or servers in various languages. Additional utilities can also take advantage of the resulting files, such as testing tools.

Benefits

OpenAPI is a simple yet powerful representation of RESTful APIs. With the largest ecosystem of API tooling on the planet, like thousands of developers we are now supporting OpenAPI 2.0 in almost every modern programming language and deployment environment. With our OpenAPI/Swagger 2.0 enabled API, you can generate client libraries in dozens of languages. OpenAPI 2.0 may help while working with the PTV Drive&Arrive API.

The PTV Drive&Arrive API supported OpenAPI specifications:

Drive&Arrive OpenAPI Spec v2.0 (Swagger 2.0)

Drive&Arrive OpenAPI Spec v3.0

Swagger Editor

Using the Swagger Online Editor

To access the Swagger online editor, click the following link.

Online Swagger Editor

• To clean the default loaded specification - File -> Clear editor

• To import an existing specification from the File -> Import URL and insert Drive&Arrive OpenAPI Spec v2.0 ...

now you could see the OpenAPI 2.0 definition on the left and the generated Swagger endpoints with models on the right. Under the menu Generate Client it's possible to generate the client stubs in a lot of different languages e.g. csharp.

The online editor work if you are working on only one API without any externalized references. If you want to work with multiple APIs, you have to run the editor locally.

Running Swagger Editor locally

  
	git clone https://github.com/swagger-api/swagger-editor.git
	cd swagger-editor
	npm install
	npm start

now your default browser will be started and point to 127.0.0.1:3001 with a sample specification loaded.

Generating Clients

Depending on what language you are using, you may be able to generate PTV Drive&Arrive API client libraries. See the Swagger site for a complete list of integrations.

Microsoft Visual Studio Pitlfalls

Please avoid generating the clients with the Microsoft Visual Studio project context menu Add/REST API Client... in the solution explorer because at the moment it is not possible to configure the AutoRest generator (which will be used under the hood in VS) and by default AutoRest generates DateTime typed properties in generated C# code for OpenAPI properties/parameters that have string as the type and date-time as the format instead of the required DateTimeOffset type. Therefore the only possible way at the moment to generate these properties as DateTimeOffset instead of DateTime in C# is when use-datetimeoffset parameter is passed via the command line.

To use the AutoRest parameter use-datetimeoffset you should install the AutoRest Node.js generator:

  
	REM install chocolatey the package manager for windows 
	call powershell -NoProfile -InputFormat None -ExecutionPolicy Bypass -Command "iex ((New-Object System.Net.WebClient).DownloadString('https://chocolatey.org/install.ps1'))" && SET "PATH=%PATH%;%ALLUSERSPROFILE%\chocolatey\bin"
	REM install the nodejs with chocolatey 
	choco install nodejs-lts -y --force
	REM instal autorest globally
	npm install -g autorest

now please generate the c# PTV Drive&Arrive API clients:

  
	REM autorest command line parameter: https://github.com/Azure/autorest/blob/master/docs/user/cli.md
	
	REM remove the old clients
	rmdir .\PTVDriveAndArriveClient\ /S /Q
	REM download the current PTV Drive&Arrive OpenAPI Spec
	powershell -command "iwr https://driveandarrive.cloud.ptvgroup.com/em/openapi2 -o dave.json
	REM generate the csharp clients
	autorest --version=latest --input-file=dave.json --output-folder=./PTVDriveAndArriveClient/ --namespace=Ptvag.DriveAndArrive.Client --add-credentials --use-datetimeoffset --sync-methods=all --csharp

AutoRest Generator supports C#, Go, Node.js, Python and Ruby.

Download PTV Drive&Arrive API Clients

AutoRest pre-generated API Clients ready to download:

C#

Node.js

Python

Go

Ruby