Refactor compile_to_openapi30 function

[mrshll1001]

The schema tools support generating OpenAPI 3.0 from an OpenAPI 3.1 openapi.json file, with the purposes of being compatible with SwaggerUI pages. This is provided by a function starting on L443, called compile_to_openapi30().

Currently this function takes two parameters: schemas_path docs_dir, finds the openapi.json file, generates the compiled 3.0 version, and writes it to a hard-coded path underneath docs_dir.

I think it would be better if this function behaved more like the schemas_to_datapackage CLI command / function, where it simply returns the output as a string rather than having the side-effect of creating the file. Instead of a schemas_path parameter, it should take a path directly to the openapi.json file that it's refactoring.

We could then:

• expose the command via the CLI interface, allowing people to generate the file and pipe it to a file, or as input to another program.
• support Profile documentation with this functionality.

For the latter, it's clear that this was intended because a call to this function is commented out on L593 within the profile_all() function.

This would also require some light refactoring some other functions where a call to compile_to_openapi30() is made, such as docs_all(), but would make the code more modular and sustainable as well as providing more functionality to end-users.

[mrshll1001]

In this branch I've begun the work.

To avoid borking the existing code, I've defined a new function _openapi31_to_openapi30() on L450, along with a function that exposes it to the CLI and prints the result as a string. It seems to work, as I got the OR UK Profile test build docs to render the SwaggerUI page simply by calling the function on their openapi.json file and piping the results through JQ and into the appropriate file.

I originally thought it was de-referencing a lot of things, but apparently all that's different between the two is the openapi version number, and the lack of a jsonschemadialect property.

If this is acceptable, then I think the next step of refactoring would simply be to modify the original compile_to_openapi30() call to assemble a filepath to pass down to the _openapi31_to_openapi30() function and write the result to the target directory, with an interim step of adding in the default copy to the info block.

[Bjwebb]

This is looking good so far.