bricks-cloud
Add openAPI/Swagger documentation for the endpoints
Please consider adding openAPI documentation for the endpoints and make it available on e.g. the /swagger path.
I'm happy to see frequent updates to this awesome project but it can be a struggle to keep documentation and implementation in sync. E.g I can't get the the GET /api/events to work given the current documentation
Hey Per, it is a good point. Might take some time to make this happen. May I ask what is the error code and error message for GET /api/events failure?
Yes, openAPI/Swagger really helps with integration and it lives with the code - or if you prefer design-before-code, in the specifications.
In the end it turned out that I sent parameters in the request body instead of the query so Mea Culpa. The error code indicated missing parameters and I made futile changes to the request body. But on the other hand, the new /api/v2/events didn't make it to the documentation ;o)
I hope it's Ok that I post a few more suggestions. My own Golang journey is brief and steep, but I like the language and development model.
/Per
You should definitely post more suggestions because we want to improve the product as much as we can. The v2 endpoint is still subject to change which is why I haven't documented it yet.
Swagger for admin server: https://bricks-cloud.github.io/BricksLLM/admin Swagger for proxy server: https://bricks-cloud.github.io/BricksLLM/proxy
Great work, this will be helpful!
I detect a small error that has snuck into the (global?) swagger definitions.
- If looking at e.g. the Admin service GET /api/health; Clicking "Try it out" and "execute" will present the below Curl command.
Admin service: GET /api/health
curl -X 'GET'
'localhost://bricks-cloud.github.io8001/api/health'
-H 'accept: /'
Here the Url seems to be malformed. "http://bricks-cloud.github.io:8001/api/health" seems more likely. The same goes for other methods for both APIs.
E.g. the Proxy service:
curl -X 'GET'
'localhost://bricks-cloud.github.io8002/api/health'
-H 'accept: /'
- Will the services on bricks-cloud use port 8001/8002 or could this be a development reminisce?
Hey per. the documentation is for local development, not connected to our cloud hosted version yet. therefore, curl won't work as for now
Great work, this will be helpful!
I detect a small error that has snuck into the (global?) swagger definitions.
- If looking at e.g. the Admin service GET /api/health; Clicking "Try it out" and "execute" will present the below Curl command.
Admin service: GET /api/health
curl -X 'GET' 'localhost://bricks-cloud.github.io8001/api/health' -H 'accept: /'
Here the Url seems to be malformed. "http://bricks-cloud.github.io:8001/api/health" seems more likely. The same goes for other methods for both APIs.
E.g. the Proxy service: curl -X 'GET' 'localhost://bricks-cloud.github.io8002/api/health' -H 'accept: /'
- Will the services on bricks-cloud use port 8001/8002 or could this be a development reminisce?