Couldn't we rather have them in the website repository, garagehq.deuxfleurs.fr ?
This looks like it's going to be a lot of work to update the API specification file and regenerate everything when we will need to update the admin API. Can you talk about how you plan to manage this complexity? Do you commit to maintaining this part of the ecosystem in the future?
We can put the Redocly dependencies (fonts, css, js, etc.) in GarageHQ but we will loose a way to visualize and check the spec from Garage's repository. I have no strong opinion on that, feel free to do what you prefer here, we might find a tool that would be easy to install and that could be used to validate the file, without having to rely on this html+css+js viewer.
Concerning the API specification part, if we consider the API is designed to connect Garage to other software, we will have to maintain more or less stable interfaces over time, so I think clearly defining it is important. I would also prefer that we define the API first and then implement the code in a second time.
In practise, I just noticed that my specification is already outdated. I think that we can live with it as long as the change is backward compatible.
I also plan to use the Smithy IDL (Interface Definition Language) instead of OpenAPI which seems to be both less verbose, more versatile and more precise. If we want to reduce the complexity of maintaining both a specification and some codes, we could use some code generation tools (smithy can output an openapi spec than can be used to generate rust server code, or more directly, amazon has smithy-rs that can directly generate rust client+server code).
Directly writing our own Rust macros is also an option: Smithy can output machine readable JSON that could be used to generate our code for the JSON structures (aka the models in Smithy, schema in OpenAPI, and the serde strutures in our code) and the services endpoints, it would probably result in a more efficient and better tailored solution. I don't know if you want to follow this path, personally I don't find it necessary as long as we are able to stabilize APIs, but writing macros from the Smithy JSON output would be an interesting challenge ;-)
More generally, I think that my future work on Garage will be dedicated to create an ecosystem around it: I have the feeling that we have accomplished a lot and now, we must "unlock" this work to others by making it accessible/usable.
I would like to see Garage becoming an alternative to both Netlify/Vercel and Firebase/Firestore services. Given this goal, specifying clear interfaces on the K2V and administration API and having easy to use SDK for popular languages seems to be important. Being busy, I can't commit on being always available, but yes I think I can be listed as the maintainer of the Garage SDKs for now.