search

pushbits / server

A simple server for push notifications via Matrix (and a minimalistic alternative to Pushover and Gotify) 🚀📯
https://www.pushbits.io
ISC License
305 stars 18 forks source link

OpenAPI documentation #37

Closed CubicrootXYZ closed 2 years ago

CubicrootXYZ commented 3 years ago

Add OpenAPI documentation compatible with swag and a workflow to push a static html to website

eikendev commented 3 years ago

I see three valid approaches here:

  1. The logic to generate the doc lives in /server. That's the case with your proposed workflow. We will need to push a commit to another repository, which I don't know I like too much.
  2. The logic to generate the doc lives in /website. A push to /server triggers a workflow that somehow triggers a workflow in /website (need to check if this is easily doable). That workflow now clones /server, builds the doc, and then the website.
  3. The logic to generate the doc lives in /website. Our /website repository has /server as a submodule (which pins to a specific commit), which is checked out when /website is built. When we think it is time to update our docs, we update the commit of our submodule in /website.

I feel like (3) is the cleanest, but we will not have a doc for the latest commit in /server without manually keeping up to date. Anyway, if we only show the doc of one specific version, that version should be a "stable" one. Now I know PushBits is not as far as having a "stable" version, but maybe for the time being we agree on the submodule commit individually? Which option do you prefer?

CubicrootXYZ commented 3 years ago

I am no fan of manual interaction as it is pron to errors. If you do not like the logic for generatin the docu in this repo I'd go with 2. we can use repository dispatches for that.

eikendev commented 2 years ago

My main concern is using a personal access token (PAT) that has a broader scope than needed. I do not think there is currently a way to restrict a PAT to a subset of repositories. If we can work around that, I'm fine with (1) and (2) also. It seems like deploy keys can also be used to write to a repository. Maybe we could put a deploy key for /website as a secret in /server, and use it to push the generated artifacts?

CubicrootXYZ commented 2 years ago

Ah sorry overlooked that the dispatches needs auth too. Yeah I think the deploy key should work best then. Let's try with one.

eikendev commented 2 years ago

We now have a WEBSITE_DEPLOY_KEY in this repo's environment. It's a private SSH key, and I think to use it we need to store it somewhere as a file during deployment. It has write access to /server.

CubicrootXYZ commented 2 years ago

Implemented the push to the website repo - works well.

However I do not know where the warnings about multiple declarations of routes come. They are defined only once.

We know need to think about:

  1. A contact url (or leave empty)
  2. Inprint/legal stuff
eikendev commented 2 years ago

Nice, I wasn't aware this already pushes into /website. I've enabled GitHub Pages for it, so we can now see it live at https://pushbits.github.io/website/. For the contact information, we can link to my (and if you like your) website. For legal stuff, we should give the license of the source (ISC). Anything else on your mind?

CubicrootXYZ commented 2 years ago

I added your website as contact, linked the pushbits team as general URL and added the license. For me it is ready to merge.