Better API documentation

[CubicrootXYZ]

Make a better API documentation. I think there are to much endpoints to do that in a (sinlge) Markdown-File anymore.

Either split it up into multipe files (and use the github wiki functionality) or use another tool for api documentation.

[eikendev]

Agree. Integrating with Swagger would be a bonus. And preferably (for the API at least) auto-generate from code and comments. Would also check Gotify here for guidance.

[kamilr]

@eikendev could You also please add initialization docs. I'm fighting to resolve endless issues. Need to read Your code do use it. In example I want to try Your solution.

1. add docker-compose
2. add to reverse-proxy
3. run - first failure, missing db -should by created by myself right? Then, created.
4. errors with config, ok, config updated
5. error with adding application - missing table users. Do I need to create that table, what columns, what types, how many other tables also, I can see that table applications is also needed?
6. server crashing due to trying to write into read-only db etc. etc.

If some action are required on initialization please write about it.

[eikendev]

Hi @kamilr, thanks for your message. I agree that this is an important issue, but I did not get to properly set this up. While adding detailed docs is great for the users, it induces quite a bit of overhead for developers: each change might require us to update the docs, too. So I won't promise to fix this in the near future, but will keep in as one of the next major steps of this project. Also, more ideas are truly welcome.

However, I would like to help you sort out your specific problems. Can you tell me a bit more about your setup? What database backend did you use? How did your compose file look like (remove sensitive info)? Are you using Podman or Docker?

When using sqlite, the database file should be created automatically with the correct permissions and all required columns.

[kamilr]

Thank You @eikendev for fast response. I understand. Work in progress. Thought that just client is in beta state. Nevertheless, maybe I can help You with this?

I'm very thankful for helping hand, maybe we can discuss about it via @stonson:matrix.org ? (Using sqlite, was not created automatically)

[CubicrootXYZ]

I implemented a swagger documentation solution in my own repo a few days ago. We really could go with swag and redoc hosted with github pages.

Maybe with a new repo for the html and yaml file so this one is not polluted to much. Implementation in pipelines is also straight forward.

[eikendev]

I created a new repository for this: pushbits/website. Happy to start with your proposed solution. Do you want to create a pull request? Later, we might want to wrap docsy or something similar around it.

[CubicrootXYZ]

For pushing the documentation to the website repo we will need an api token for that repository set here as a secret. We can use the push-a-file-to-another-repository, push-directory-to-another-repository actions or do it ourself (git clone => git commit => git push) to get the documentation there. Any preferences?

[eikendev]

Let's move the discussion to #37.

[eikendev]

We got a new little page running at pushbits.io. @CubicrootXYZ worked out a way to neatly document the API, available here.