Aircoookie
Add OpenApi support (formerly Swagger)
It would be really cool if the json api also served a (static) swagger.json file which would make 'discovering' and more importantly implementing the API a lot simpler (automatic client generation on most plaforms and languages). It also serves as (machine readable) documentation. Adding a (also static) swagger-UI would be extra bonuspoints.
Basic steps:
- [ ] Write the
swagger.json - [ ] handle the
/json/swagger.jsonrequest by serving the static file (I guess here somehwere) - [ ] (Optional) Also serve the required (static) swagger-ui files
Ofcourse, this would mean that when changes are made to the api this document needs to be kept in sync. But I do really think it would be worth the effort.
This would require some storage, naturally, but the files can be saved pre-gzipped (or brotli or whatever is hot nowadays) and served as-is (with the correct headers).
I could (help with) write the swagger.json file, but I'm not sure on the other two steps. If anyone is interested in helping or teaming up I would love to prepare a PR. But if there's no interest then I won't make all these efforts in the first place. So: is there interest?
I would also love this. I've not really done cpp development but I'm happy to take a stab at it
Googling around suggests that there isn't quite a way to make an automatic generation of the swagger document from the code. I played around a bit and at an embedded level I just don't think we are going to get the type of compiler/interpreter support to auto generate such a file.
So then it comes down to just creating a swagger.json manually. I think that is how this is going to move forward. Again, I'm down to give it a shot. I do get the sense that these devices are so memory constrained that hosting random json/yaml files is going to push us past the limits. This is way out of my wheelhouse.
Anyway, I still think I'm down to try to manually create the swagger doc.
Yeah you won't be able to use any automatic generation due to the lack of reflection in C++
There is no need to include the swagger-ui as you can just include a link to open https;//editor.swagger.io/ which will help save space
If it's being build manually then perhaps we host the spec file from WLED-Docs, if we can pass the server URL to the editor as well as the spec
I've just published a tested multi-file OpenAPI 3.0 Schema for WLED 0.15.0 at https://github.com/13rac1/openapi-wled
Hi @13rac1 , thanks for sharing that. It looks like it was AI generated. Can you give a little more detail as to how it was generated and how/who it would be maintained going forward?
Hi @netmindz ! I assume you suspect vibe coding. That's understandable, I'm not offended, there's a lot of irritating slop lately. I submit this isn't that, but I'm open to being proved wrong.
To start, please note the use of verification and validation tools in the package.json. There are schema validation tests against sanitized JSON captured from real device HTTP GET requests and those scripts are themselves unit tested. There are also E2E unit tests using a JS API client generated (during the tests using https://github.com/OpenAPITools/openapi-generator not a LLM) from the bundled schema against actual devices to test GET and POST [example results]. I could increase the testing coverage, but I believe it is sufficient at this point. I've used the schema to generate a Python API client with https://github.com/openapi-generators/openapi-python-client which is working well for my use case.
How it was built, in summary: I started with the Rust client library, but switched to working directly with the C++ implementation once reaching the limits of the Rust library. I used Redocly's multi-file OpenAPI Schema format to mitigate LLM context size limitations. Then progressively working endpoint by endpoint or, in the case of /json/config, object by object to translate the C++ into OpenAPI YAML. Every YAML file has been separately verified after generation at least twice compared to the source code. At its core this is a simple, but tedious translation project. Do you want more details? Let's talk live.
Updating for new versions is straightforward. Run the collection script against a device with a new WLED version, run the sanitizer to remove PII, commit the captured JSON, run the tests to find if any fields don't match the collected data. Then, either manually update the YAML schema or request that the LLM does it by comparing the WLED json.cpp. The multi-file format greatly reduces the maintenance complexity for machine and humans.
I'm not suggesting this project be integrated upstream at this point, although it could be. The schema covers the JSON API for version 0.15.0. I haven't decided what the project maintenance schedule will be. I need more automation for this and my other projects too.
Do you have any other questions? LMK!
Just FYI; Not all API commands are visible via /state or /info responses. WLED also implements custom JSON mangling (alongside ArduinoJson's parsing). I.e. "on":"t" will toggle on state or "bri":"10~50~5" which will cycle between 10 & 50 in steps of 5, etc.
Your commits are literally coauthored by an ai bot, then you think I can't spot you used an AI to create your rebuttal
Nice trolling attempt 👏🏼 😆 How is this relevant to the topic? Please review https://github.com/wled/WLED/blob/main/CODE_OF_CONDUCT.md before replying.
This is how I write, full sentences with proper grammar and markdown formatting for clarity. I don't need a bot for this. Feel free to review my decade+ of Github history, there are numerous examples of my writing style. Would you like to see the history of the Google Keep Note where I originally drafted the original comment? How about my Firefox history collecting all of those links to be thorough? I've got screenshots 💻
Nitpick: The generated code was committed with git commit --author. I am just the committer, not the co-author on those commits. I've renamed and reused an old DevOps-automation machine account account for this purpose.
This text is pure artisanal human keyboarding, no AI was used!!one 🙃
Why would a human say "I submit this isn't that, but I'm open to being proved wrong." If you didn't use AI, then you would know that to be a fact and nobody else could persuade you that you did
In terms of it's relevance, my question is entirely relevant as if you are wanting this to be listed as in official place for documentation or have your repo imported into the WLED org then it's important that as the maintainer I understand if this documentation is going to be maintained. Doing a one time operation and having a workflow that you can use going forward are very different things.
Nothing in my original message said anything negative about ai usage, simply asking to know more so that I could understand your workflow