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:
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.
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:
Repetition / redefinition of the parameters member in the paths section e.g. paths./companies.get.parameters
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.
The files/schemas are “incorrectly” referenced within the json - you simply need to replace the domain:port (mine was 127.0.0.1:31871/) portion with developer-specs.company-information.service.gov.uk
PS: once you download the first schema, it is a simple case of replacing that and when you import it’ll correctly resolve.
Is the expectation to go through each and every reference link manually and do a “find and replace” or am I missing something obvious here that will allow me to it all in 1 action?
Yes, that’s the issue here! linked json files may also have reference links that are “broken”.
You’ll have to download all the referenced files locally AND will also have to edit each reference to remove the port (not the domain as they’d now be hosted locally).
Wow ok! I was afraid you would say that. There are roughly ~30 reference links on the main JSON. If each one has an additional 3-4 reference links, that’s roughly ~100 JSON files we would need to download and update, manually and 1 at a time.
Does that sound about right? Is there really no way to obtain all the files at once?
Thanks again for all your quick support! This is really helpful. I was pulling my hair out trying to figure this out!
This is NOT support! I am simply a user sharing my experience dealing with the CH API.
But yes, looks like you’d need to do exactly as you say. As for there being a better way to download the files, I know not of another (but may be I haven’t looked in all the right places). Saying that, CH staff have visibility on this and they can advise as appropriate.
PS: by the way, and I am sure you are aware, you can always make those references file references rather than URL references when you save them to disk.
I managed to get a complete API spec with correct references, by writing a little script that gets the entrypoint url and then resolves all JSON references, while I run a simple proxy server on localhost that redirects to developer-specs.company-information.service.gov.uk. I ended up with a single large API spec file. I know it sounds a bit ridiculous to do all this, but it worked for me.
Unfortunately I found that the response formats in the API spec do not always match the actual response formats of the API and there are inconsistencies and spelling mistakes in the API spec. Don’t rely on it as being perfect.
Wow that’s great to hear @ebrian101 . Do you mind sharing that API spec file? I’ll take it with a grain of salt considering the errors you mention. If you are willing to share, feel free to email me at: nolandsmith1@gmail.com
Thanks again! CH should really be providing simple ways to access the full API spec files. Would be a great suggestion to provide.
Sorry for a slow reply, but see this issue is getting comments elsewhere.
For the spec file that I produced please see https://github.com/mrbrianevans/companies-db/tree/master/spec on github, but bear in mind that its now 2 years old, so may be better off running the script.
If you clone the repo (or just copy/paste the file contents of the javascript scrips), you can run https://github.com/mrbrianevans/companies-db/blob/master/spec/parseSpec.js with nodejs (after installing dependencies with npm) to generate a consolidated API spec file.