Update and integrate API documentation - Githubissues

codeforIATI / iati-datastore

An open-source datastore for IATI data with RESTful web API providing XML, JSON, CSV plus ETL tools

https://datastore.codeforiati.org

Other

1 stars 1 forks source link

Update and integrate API documentation #368

Open markbrough opened 2 years ago

markbrough commented 2 years ago

Is your feature request related to a problem? Please describe.

There are a few issues with the API documentation at the moment:

it runs as a set of Sphinx scripts, separate from the rest of the front end query builder, so the user experience is a bit jarring
everything has to be manually written from scratch each time
it is not always kept up to date as API routes etc change (see #355 and #98)

Describe the solution you’d like

integrate with existing NuxtJS app (also then potentially simplifying translation)
generate basic documentation from API docstrings

Describe alternatives you’ve considered

Leaving everything more or less as it is (i.e. just updating Sphinx)

Additional context

Custom solution:

Using Swagger:

https://github.com/Elevista/nuxtswagger

odscjames commented 2 years ago

I don't have any immediate thoughts on good technical solutions but certainly the problems make sense.

I'm not sure if static help pages need to be in NuxtJS tho - I see that as having strengths for interactive pages (eg the query builder front page). Help pages could be kept simple and just be served by flask, which handily just had I18N options added.