Importing Streaming API Swagger Fails

Hello guys,

I’m facing a problem, when I try to import the swagger specs (https://developer-specs.company-information.service.gov.uk/api.ch.gov.uk-specifications/swagger-2.0/spec/streaming.json) to my OutSystems Applications and this operation fails, giving the error:
.“Invalid REST API
StreamingAPI must have at least one method.”

Can you please help?

Best regards,Screenshot 2022-02-10 125527

try importing this (for companies)
https://developer-specs.company-information.service.gov.uk/api.ch.gov.uk-specifications/swagger-2.0/spec/stream.json#/companies

Unfortunately this looks like the same issue as the main REST API specs have e.g. they’ve been put up in a form where a local host and port has been specified rather than the external host name. So all over the json you’ll see links of the form:

http://127.0.0.1:31917/api.ch.gov.uk-specifications/swagger-2.0/spec/…”

It’s simple to correct though I believe, just substitute:

"http://127.0.0.1:31917/"

for

"https://developer-specs.company-information.service.gov.uk/"

(I think you can use http but https should be fine)

This applies to the companies link above also.

Chris

Hi,

Yes, you’re right. The Swagger file was some problems.

But even, replacing the localhost address with the “https://developer-specs.company-information.service.gov.uk/”, I still can’t import the WebService, it gives me the same error. “…must have at least one method”…

Chris, do you have any other idea?

Best regards,
Steven

Hi Phillip,

Importing for the companies gives me the error “The Swagger file doesn’t have a version specified or the version is incorrect.”.

But with the feedback from “voracityemail” I notice that insite this swagger file there are still some problem with the localhost links (“http://127.0.0.1:31844/api.ch.gov.uk-specifications/swagger-2.0/models/stream/companyProfile.json#/definitions/companyProfileStream”)

I saved a local file and replace the localhost (http://127.0.0.1:31844) to (https://developer-specs.company-information.service.gov.uk/) and it still gives me the same error.

Thanks,
Steven

I don’t know exactly why you’re getting a particular error in your tool. I guess the “missing method” means that it couldn’t find the following:

(top level)
paths.(some path e.g. /companies).get (or post etc.)

If you don’t start from the main file that’s probably why it complains about missing or incorrect version - because that’s where that’s defined.

In my (limited) experience working with json schemas and in particular Swagger / OpenAPI always involves some effort. I don’t think we’ve seen one where someone published a schema and it would just work as it was. That might also be down to the tool you’re using / where you’re trying to import it to however.

You will probably need to start from the main document (otherwise you’ll be missing information like version):
https://developer-specs.company-information.service.gov.uk/api.ch.gov.uk-specifications/swagger-2.0/spec/streaming.json

The “$ref” JSON pointer is used frequently in the CH schema. That means files can reference other files, which in turn can reference other files, files can reference themselves (either “internally” using “#” or with a host / path prefix) etc. So you’d have to ensure that all such references to e.g. "http://127.0.0.1:31917/" work. That means if you create a local copy of one file with correct refs, the files it pulls in will still have incorrect refs, and when corrected those in turn will likely reference another file with the same issue etc.)

There are different ways you can fix this. However as a quick test I was able to get one end-point to “work” (see below). I did that by manually including the appropriate details in definitions and correcting the refs to point there (internally).

So if there is a referenced file at:
http://something/path/spec.json#/definitions/blah
…which contains
{ "definitions": { contents here } }
… you can add the contents to the main file’s definitions (create one at the top level if not there).
The reference should be changed to:
#/definitions/blah
…and you’ll need to do the same with everything in the contents.

However even then I found issues - which your tool may or may not complain about:

  1. Repetition / redefinition of the parameters member in the paths section e.g. paths./companies.get.parameters

  2. Read only properties marked as “required”
    Semantic error at definitions.streamEnvelope.required.0
    Read only properties cannot be marked as required by a schema.

There are various ways you could resolve all this. For info you could try putting stuff into Swagger’s (well, SmartBear’s) own interactive editor / validator at:
https://editor.swagger.io/
They have a parser / validator too at:

I’m sure you can make this work. It’s hacky but in my experience this is not unusual! Good luck.

In that case, you’ll need to download ALL the files referenced and fix the references to point to the local files in each file (starting at the very top). That should fix it.