Serve an official OpenAPI spec?

another-guy commented 1 year ago

Is your proposal related to a problem?

Cal.com service API is unclear. The documentation under https://cal.com/docs/enterprise-features/api is lacking necessary details for reliable integration. E.g. what's the shape of EventType object? Which fields are required, which are optional, and so on.

Describe the solution you'd like

Post an official automatically generated documentation in two forms:

openapi.json/yml for machines and humans
the interactive HTML version of the above (swagger or similar)

Describe alternatives you've considered

Not sure

House rules

If this issue has a 🚨 needs approval label, don't start coding yet. Wait until a core member approves feature request by removing this label, then you can start coding.
- For clarity: Non-core member issues automatically get the 🚨 needs approval label.
- Your feature ideas are invaluable to us! However, they undergo review to ensure alignment with the product's direction.

alishaz-polymath commented 1 year ago

Thank you for your suggestion. We're in the middle of reworking the API docs, and this suggestion will definitely be taken into consideration 🙏

cmgriffing commented 1 year ago

I recently did some discovery around this and found some interesting info.

The public URL is: https://api.cal.com/docs However, that spec is missing all of the paths for each tag.

Curiously, if you pull down the repo and run the API app directly, you will get a full spec with the paths:

cd apps/api
yarn dev
curl http://localhost:3002/docs

I'm uncertain of where the script for deploying the API lives, but my first guess would be to look at that and try and figure out why the production URL is missing the paths from the OpenAPI spec.

next-swagger-doc seems to be the library responsible for generating the spec. https://github.com/jellydn/next-swagger-doc Updating to the latest version did not seem to have any effect in my local testing.

cmgriffing commented 12 months ago

I just had a random thought. Is it possible that the deploy script is stripping the comments from the code before deploy? This would mean that next-swagger-doc wouldn't be able to see the @swagger JSDocTag since it got removed.

Not sure, but a random thought I had that might help someone with higher access privileges troubleshoot this.

CodeFromAnywhere commented 5 months ago

Curious on the status of this.

calcom / cal.com