-
Notifications
You must be signed in to change notification settings - Fork 17
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Better API documentation #31
Comments
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. |
@eikendev could You also please add initialization docs. I'm fighting to resolve endless issues. Need to read Your code do use it.
If some action are required on initialization please write about it. |
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. |
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. |
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. |
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? |
Let's move the discussion to #37. |
We got a new little page running at pushbits.io. @CubicrootXYZ worked out a way to neatly document the API, available here. |
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.
The text was updated successfully, but these errors were encountered: