search

bricks-cloud / BricksLLM

🔒 Enterprise-grade API gateway that helps you monitor and impose cost or rate limits per API key. Get fine-grained access control and monitoring per user, application, or environment. Supports OpenAI, Azure OpenAI, Anthropic, vLLM, and open-source LLMs.
https://trybricks.ai/
MIT License
863 stars 60 forks source link

Add openAPI/Swagger documentation for the endpoints #53

Closed perrauer closed 2 months ago

perrauer commented 4 months ago

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

spikelu2016 commented 4 months ago

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?

perrauer commented 4 months ago

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

spikelu2016 commented 4 months ago

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.

spikelu2016 commented 3 months ago

Update: Just added documentation for the v2 events API

spikelu2016 commented 2 months ago

Swagger for admin server: https://bricks-cloud.github.io/BricksLLM/admin Swagger for proxy server: https://bricks-cloud.github.io/BricksLLM/proxy

perrauer commented 2 months ago

Great work, this will be helpful!

I detect a small error that has snuck into the (global?) swagger definitions.

1) 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: /'

2) Will the services on bricks-cloud use port 8001/8002 or could this be a development reminisce?

spikelu2016 commented 2 months ago

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.

  1. 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: /'

  1. Will the services on bricks-cloud use port 8001/8002 or could this be a development reminisce?