Openapi definition

[PhilippJust]

Although the documentation of the public api is very good, I'd like to include an openapi definition to allow auto generation of client code. I think this might help developers consuming the api with whatever technology they are using as there are code generators for a load of languages and frameworks out there.

Any thoughts or obligations? Otherwise I'd start writing it and open a pull request. Question would be: Where should be? Inside /docs/api?

[mtmail]

@PhilippJust We're not sure yet which file location is best. The hostname is probably hardcoded in that file so we'd need to replace it during a Nominatim installation.

Let's use the /website directory, that's where the OpenSearch definition file a crossdomain.xml are currently placed.

https://nominatim.openstreetmap.org/nominatim.xml https://nominatim.openstreetmap.org/crossdomain.xml

[BioPhoton]

Is there any progress? Would need this: :)

[lonvia]

Not as far as I'm aware. Happy to take a PR on this. I would suggest to put a template into /website and install it with ./utils/setup.php --setup-website. At least termsofservice and contact need to be configurable.

[PhilippJust]

Sorry, I originally wanted to go about it but I struggled a lot because the query parameters have a very heavy effect on how the output looks. That's something I couldn't work out to describe elegantly in OpenApi.

[lonvia]

Sorry, I originally wanted to go about it but I struggled a lot because the query parameters have a very heavy effect on how the output looks. That's something I couldn't work out to describe elegantly in OpenApi.

I was afraid of that, which is why I initially tagged the issue with APIv2. You might get away with defining a separate operation for each format type.

[namelus]

I'd like to help with this effort. Kindly advise on next steps.

Thanks,

[lonvia]

You basically have to take the documentation from https://nominatim.org/release-docs/latest/api/Overview/ and convert it into the format as defined in the OpenAPI specification.

[jenkin]

@lonvia We just released the OpenAPI specification of Nominatim API, describing the latest 4.3.2 version: https://github.com/sparkfabrik/nominatim-openapi/releases/tag/v4.3.2

The spec defines also the JSON schema of responses, preferring geocodejson format. It can be explored using the public swagger ui: https://sparkfabrik.github.io/nominatim-openapi/

Please read the README for all details and feel free to ask me anything here or opening issues. Thanks!

cc @PhilippJust @BioPhoton @namelus