Improvements/fixes for openapi.json

[giovannipizzi]

After the issue that @CasperWA found in #306, I gave a look to the openapi.json file.
I admit I'm not 100% sure of understanding it, so some comments here are wrong.

• Shouldn't type still be required for links? It has been removed here

• Probably the error @CasperWA was finding is that the correct way to specify possible values is via an enum? Here in Update links resources #306 there was an attempt of using anyOf, then reverted. Maybe @CasperWA you can try to use enums and check if it works (and maybe check if there are other points were we should use enum as well?

• By looking at the way you tried to use anyOf, and then check the docs of swagger, I got the impression you actually mean oneOf, at least in that case. Here are the docs explaining the difference (oneOf means exactly one of the two, anyOf means any combination of the two schemas). This raises a doubt: are we using anyOf/oneOf correctly in the openapi.json and index_openapi.json files? Just to make an example:

  https://github.com/Materials-Consortia/optimade-python-tools/blob/master/openapi/index_openapi.json#L23

  Should this be either a response or an error, or a combination of them is also OK? I don't remember the specs, but this is just to raise awareness and trigger a careful check of the schema.

[CasperWA]

Thanks for the report and considerations @giovannipizzi.
These are all valid points that ends up (at least for point 1 and 3) pointing to a recheck of how the OpenAPI JSON files are generated in certain situations from the pydantic models.

Point 2 is remedied by pydantic validators, but we could instead move to enums, for sure. If there is a schema-generating difference, and we find it's more accurate for one or the other, we should use the better one, however, if there is no difference in the schema generated with these two approaches, I consider it a development choice, and something we don't wish to change at this stage, since it will not alter any functionality or validation otherwise.

[CasperWA]

Leaving this here for reference of updated behaviour of enums in OpenAPI scheme generation through FastAPI (they are treated as models).

[CasperWA]

FastAPI also has extensive documentation on customizing and extending the OpenAPI schemas.

[ml-evs]

It would be good to fix some of these things in parallel to updating the models, so that we can provide our best OpenAPI schema ASAP for Materials-Consortia/OPTIMADE#286

[CasperWA]

For sure - also, several of the models updates can be fixed by a single PR.

[CasperWA]

#350 implements Enums where possible, hence solving the 2nd point in the OP.