search

benetech / Imageshare

MIT License
0 stars 0 forks source link

Discuss API Documentation Strategy #252

Closed clapierre closed 3 years ago

clapierre commented 3 years ago

Maybe a Github action to keep documentation up to date ...

sinabahram commented 3 years ago

@jkva can we discuss in this ticket the approach we are using for the JSON API documentation. @johnhbenetech I'd like to hopefully do this in such a way that it is automatically generated for you via a GitHub action, but let's discuss that once Job updates us on documentation approach.

jkva commented 3 years ago

I would suggest I write a yaml spec of the OpenAPI implementation the server follows - such as seen on https://editor.swagger.io/. This can then be used to generate similar documentation.

sinabahram commented 3 years ago

@johnhbenetech you good with the above?

johnhbenetech commented 3 years ago

@sinabahram @jkva works for me

jkva commented 3 years ago

The current implementation has been written to follow the json-api spec; Swagger speaks openapi. While I could modify the request/response cycle to implement openapi instead, it's currently an fairly simple read-only api. Moving to another spec seems overkill. I've added documentation in the main plugin README for now, eventually this might move to its own separate markdown file and be linked to from the main README.

jkva commented 3 years ago

Following up; if autogenerating documentation is a strongly desired feature, I can modify things accordingly to implement an openapi compliant api. But given the current simplicity of the API I wonder if that's needed. @johnhbenetech what do you think?

johnhbenetech commented 3 years ago

@jkva README seems adequate. I don't imagine this changing frequently and significantly, so shouldnt be too much of a hassle.

jkva commented 3 years ago

Closing as adequately addressed.