I'm just adding openapi specs for Valhalla, see e.g. here for UI with Redoc: valhalla/valhalla#6088 (comment).
It's just a yaml, Redoc supports embedding in existing docs via <script> element for rendering. For Valhalla it's a lot, but for OSRM it'd be super easy, also to maintain (openapi is pretty easy to understand for what we need). Swagger is also an option for UI/UX, but IMHO it's worse UX than Redoc. However, it supports sending live requests to the public service inside the Swagger UI. I never found that feature too useful, assuming there's no drift in the openapi specs.
Would that be interesting to replace the current API docs eventually? It's not a lot of work and can be done step by step, e.g. first define request schemas, later define response schemas.
I'm just adding openapi specs for Valhalla, see e.g. here for UI with Redoc: valhalla/valhalla#6088 (comment).
It's just a yaml, Redoc supports embedding in existing docs via
<script>element for rendering. For Valhalla it's a lot, but for OSRM it'd be super easy, also to maintain (openapi is pretty easy to understand for what we need). Swagger is also an option for UI/UX, but IMHO it's worse UX than Redoc. However, it supports sending live requests to the public service inside the Swagger UI. I never found that feature too useful, assuming there's no drift in the openapi specs.Would that be interesting to replace the current API docs eventually? It's not a lot of work and can be done step by step, e.g. first define request schemas, later define response schemas.