DELFT-FEWS OpenAPI Python Client Generation

This repository contains the generated Python client for the DELFT-FEWS OpenAPI specification. The client is generated using the OpenAPI Generator tool, which allows for easy integration with the DELFT-FEWS REST API.

Delta-FEWS has an OpenAPI spec listen in the documentation.

https://fewsdocs.deltares.nl/webservices/rest-api/v1/delft-fews-webservices-rest-api-v1-oas3.json

Unfortunately, I can't just shove this into a code generator and have it work. Either the OpenAPI spec has some issues that prevent the generation of a fully functional client, or the code generators I tested doesn't fully support the spec, or I'm doing something wrong. We need to do some pre-processing and some custom templates.

The following issues can be solved in pre-processing:

1. Some of the content types (return types) don't work. I'm not sure if they're ill defined in the spec, or if the code generator just doesn't support them.
2. External references are not supported. The spec has a whole lot of $refs pointing to something called pirest schemas, which needs to be resolved.
3. The components seem to be "out of order". It seems like the code generator works in a top-down manner, so if components are referenced before they are defined, it breaks.

And these issues can be addressed with custom templates (maybe, not sure yet):

1. Strict Enums. Enums are like "multiple choice" options, and by default the code generator defines these as data classes that need to be imported and defined as objects. It can't just take and validate strings. This seems like an issue to me, but I'm still deciding if it's worth fixing.
2. Return types. As far as I can tell the generator cannot handle multiple return types. It seems to choose the first return type and not allow any others. I'm not sure if I can even fix this with templates tbh but I can try.
3. Actually, it looks like the generator can't handle any return types that aren't json? Could that be true?
4. The docstrings are nasty. And no module docstrings? Could possible solve this with a nice ruff post-hook.

Pre-Processing

The pre-processing script is in fix_openapi.py.

• 'plain/text' -> 'text/plain'
• '*/*' -> 'application/json'
• 'application/zip' -> 'application/octet-stream'
• 'image/png' -> 'application/octet-stream'
• 'application/xml' -> 'text/xml'

These subs are specified in the client_config.yaml

In addition, the spec contains a whole lot of external references to something called pirest schemas. They were not very forthcoming with this schema, but I found it in an open directory here:

https://fewsdocs.deltares.nl/webservices/rest-api/v1/schemas/pirest/

I decided to dump this directory and sub each reference. Here is how I did the dump:

mkdir -p schemas/pirest
cd schemas/pirest

wget --recursive --no-parent --accept "*.json" \
    https://fewsdocs.deltares.nl/webservices/rest-api/v1/schemas/pirest/

And the subbing happens in the fix_openapi.py script.