Swagger file outdated?

Unified API
#1

The Swagger file at https://api.tfl.gov.uk/swagger/docs/v1 seems to refer to the (somewhat outdated) https://api.tfl.gov.uk/swagger/ui/index.html instead of the newer https://api-portal.tfl.gov.uk/apis.
If you paste it into a swagger editor, you can see many issues:

Note: the LineStatus path isn’t the only path with most of these issues, but it does show them clearly.

I ran into these issues after realising that none of the response attributes are marked as required, implying every field in the response could be undefined / missing, which causes issues when using the Swagger file to generate TypeScript files. (see issue on Github for more detail). Request fields are properly marked as required/optional, while response fields are not. I started looking into modifying the Swagger file myself before coming across these inconsistencies.

I therefore have 2 requests:

  1. Is there any updated Swagger file available which is consistent with https://api-portal.tfl.gov.uk/apis?
  2. Is it possible to have the latest available Swagger file updated to include required definitions for the response types?
#2

Updating the swagger file and keeping up to date would be really helpful as it allows packages such as the JS to stay up to date and be easily maintainable.

#3

Welcome @qwrwed

There are new docs here - APIs: List - Transport for London - API - which seem to have new versions of the OpenAPI format interface definitions. I’m not keen on them myself so I don’t use them.

#4

I’ve seen those new docs (my post has linked to them several times to demonstrate that the Swagger file does not match them) but there does not seem to be any way to export them into a new Swagger file or other program-readable type definition file.

#5

If I go to APIs: Details - Transport for London - API and then pick from the “API Definition” drop down list, as an example, it downloads a YAML/JSONWADL definition file.

Not a standard user interface design, I agree, but it does trigger a file/save…

#6

Thanks, I didn’t know about that. That’s very useful to have (the schemas being renamed from things like Tfl.Api.Presentation.Entities.TrainLoading to things like Tfl-4 is less useful, but still manageable).
I guess that just leaves my second request, - probably a long shot, but worth asking just in case it can be implemented upstream:

  • Is it possible to have the OpenAPI files updated on TFL’s end to indicate that the response types (e.g. Tfl, Tfl-2, Tfl-3) have properties which are required?

This would entail adding an additional field, required, to each definition like so. In e.g. Line.json,

"Tfl-2": {
    "type": "object",
    "properties": {
        "modeName": {
            "type": "string"
        },
        "severityLevel": {
            "type": "integer",
            "format": "int32"
        },
        "description": {
            "type": "string"
        }
    }
},

would become

"Tfl-2": {
    "type": "object",
    "required": [
        "modeName",
        "severityLevel",
        "description"
    ],
    "properties": {
        "modeName": {
            "type": "string"
        },
        "severityLevel": {
            "type": "integer",
            "format": "int32"
        },
        "description": {
            "type": "string"
        }
    }
},

This would be done for each schema of each API definition. Can this be done on TFL’s end or would it have to be done on our end?

#7

@qwrwed Sadly I’m only here as a user… but I can ping @jamesevans with your sensible suggestion as I believe the new help system is a work-in-progress.