I notice that inside of the “API Explorer” there’s a backend which describes all of the API Endpoints, and presents Swagger (OpenAPI) 2.0 endpoints. It looks like the underlying project is Swagger UI, with some custom backend bits written by the contractors who set this service up.
I would really like a thing I can easily hit that contains all the endpoints described with valid Swagger schemas. At present, I am emulating a bunch of calls that would normally be executed by the Javascript of Swagger UI.
After some hacking around, I’ve got something working which enumerates these endpoints from the Catalog, grabs the Application Keys, and dumps out the Swagger schemas. That’s great, but I notice some issues with the Swagger schemas. I’ve been mainly hitting the Realtime endpoints, but I suspect these issues are global.
I’m still in the process of packaging up what I’ve got, but it would be made much easier if the issues below were fixed:
Issue #1: In the Swagger description for the Vehicle Position API, there is a Response model defined, which has a type of object. I don’t think this is valid according to the spec, and indeed when I load it into an API generator for Swagger, and try to make a request, it returns an empty object because it’s unable to parse the protobuf-formatted GTFS-realtime data.
I managed to fix this in the Swagger files by tweaking the endpoints response type for 200 from:
"200" : {
"description" : "The request has been processed successfully.",
"schema" : {
"$ref" : "#/definitions/Response"
},
"examples" : {}
},
to:
"200" : {
"description" : "The request has been processed successfully.",
"schema" : {
"type" : "file"
},
"examples" : {}
},
After this, the Response definition can be removed from the schema.
Issue #2: The endpoints themselves have nonsense operationIds.
"/sydneytrains" : {
"get" : {
"operationId" : "sydneytrains_res4_method0",
/* ... */
}
}
Issue #3: The basePath attribute at the root of the Swagger schema has a stray slash at the end. This normally wouldn’t be a problem, but the extra slash causes TfNSW’s webserver to be sad:
Traceback (most recent call last):
swagger_client.rest.ApiException: (404)
Reason: Not Found
HTTP response body: {
"ErrorDetails":
{
"TransactionId":"XXXXXXXXXXXXXXXXXXX",
"ErrorDateTime":"2016-04-24T00:00:00.000+10:00",
"Message":"Requested resource was not found",
"RequestedUrl":"/v1/gtfs/vehiclepos//sydneytrains",
"RequestedMethod":"GET"
}
}
Once I hack up the schema a bit, I can call everything via the generated API. But it’s a bit ugly looking:
$ java -jar swagger-codegen-cli.jar generate -i realtime.json -l python -o py
$ cd py
$ python
import swagger_client
client = swagger_client.ApiClient(header_name='Authorization', header_value='Bearer xxxxx-xxxxxx-xxxxxxx-xxxxxxxxxx')
# Fix issue #3 by trimming the / from the end
client.host = client.host[:-1]
# Setup the SydneytrainsApi
syd_trains = swagger_client.SydneytrainsApi(client)
# Find all the trains! With this one weird method name (Issue #2)
res = syd_trains.sydneytrains_res4_method0()
# Print out the path to the protobuf blob
print res
I can then read that protobuf blob successfully.