search

SpigotMC / XenforoResourceManagerAPI

Exposes resource/author information via a simple JSON REST API
BSD 3-Clause "New" or "Revised" License
77 stars 6 forks source link

Improve documentation #47

Closed jacobsandersen closed 1 year ago

jacobsandersen commented 3 years ago

I need to thoroughly document all possible responses.

Notably I need to clarify that the native minecraft version might be formatted as a standard "decimal" (i.e. 1.16, 1.17) or it may appear as the word legacy which might be confusing to some (but hopefully, not an issue for too much longer if people will start updating.)

But I digress, I need to work on something a bit more comprehensive. Maybe on the Spigot Wiki or something?

Thoughts?

md-5 commented 3 years ago

Also the versions are sometimes null and sometimes empty string / array. Guess it depends on whether they've been set before or something.

jacobsandersen commented 3 years ago

Also the versions are sometimes null and sometimes empty string / array. Guess it depends on whether they've been set before or something.

Do you have an example of when it's an empty string? Empty array makes sense if there are none set at all, but if it's empty array and they are set then that's a bug.

Empty string may be a bug regardless but not sure.

jacobsandersen commented 3 years ago

Ah, indeed. It'll be null if never set before at all. [] (empty array) if set before and then unset.

Empty string, not sure why it would be that.

md-5 commented 3 years ago

I think the native version is an empty string if set then unset (as its not an array)

jacobsandersen commented 3 years ago

Ah yeah. Okay, that all makes sense.

This just emphasizes even more that I need to write some docs, because even I'm getting confused LOL.

MiniDigger commented 3 years ago

no clue about php land, but wouldn't it help to just throw up swagger and call it a day? that can display all requests with their params, and provide sample responses and even a way to try out requests right in the browser.

jacobsandersen commented 3 years ago

no clue about php land, but wouldn't it help to just throw up swagger and call it a day? that can display all requests with their params, and provide sample responses and even a way to try out requests right in the browser.

I have never used swagger honestly, is that something that can be integrated into this project being that there is no framework in use? (I wrote it all by hand, because it's a relatively trivial project.)

MiniDigger commented 3 years ago

mmmh, if its not possible to use swagger automatically, you can still write the swagger/opengraph file by hand, which still would be better than something you can do in markdown or smth. maybe I can look into getting that started after work

jacobsandersen commented 1 year ago

Now hosting an openapi definition which can be read by swaggerui. If desired, @md-5 could host a swagger UI static site and link to the openapi definition so people could reference it. For now, I have an example here: https://area51.jacobandersen.dev/docs/xfrm/0.2

(these docs will remain WIP but they have fairly good coverage as they are now)