Skip to content
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

Closed
CubicrootXYZ opened this issue Jun 8, 2021 · 9 comments · Fixed by #37
Closed

Better API documentation #31

CubicrootXYZ opened this issue Jun 8, 2021 · 9 comments · Fixed by #37
Assignees
Labels
documentation Improvements or additions to documentation enhancement New feature or request

Comments

@CubicrootXYZ
Copy link
Collaborator

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 eikendev added documentation Improvements or additions to documentation enhancement New feature or request labels Jun 8, 2021
@eikendev
Copy link
Member

eikendev commented Jun 8, 2021

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
Copy link

kamilr commented Sep 27, 2021

@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
Copy link
Member

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
Copy link

kamilr commented Sep 28, 2021

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
Copy link
Collaborator Author

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
Copy link
Member

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 CubicrootXYZ self-assigned this Sep 30, 2021
@CubicrootXYZ CubicrootXYZ linked a pull request Sep 30, 2021 that will close this issue
@CubicrootXYZ
Copy link
Collaborator Author

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
Copy link
Member

Let's move the discussion to #37.

@eikendev
Copy link
Member

eikendev commented Nov 1, 2021

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation Improvements or additions to documentation enhancement New feature or request
Projects
None yet
Development

Successfully merging a pull request may close this issue.

3 participants