Openapi definition
PhilippJust opened this issue · 8 comments
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?
@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
Is there any progress? Would need this: :)
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.
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.
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.
I'd like to help with this effort.
Kindly advise on next steps.
Thanks,
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.
@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!