Documentation for API Endpoints

[David Harper]

Hey,

Is there any documentation around this screen?

I've had a bit of a search but come up empty.

• What versions of spec does it support?
• Is it only YAML? Most things produce JSON?
• Is committing to the repo the only way for it to work (the older Swagger plugin had a cURL endpoint)
• It'd be nice if it showed you an example of what you were going to get by doing this process
• If I have "Enforce Jira Keys" in Bitbucket turned on, but then generate this in my pipeline, that's not going to work without a long running Jira issue just to commit these changes against, right?

[Aidan Cunniffe · Accepted solution]

Hey @David Harper - I'm Aidan (the founder of Optic, now over Compass which powers the new API tab). You're right, we need better docs here

- We support OAS 3 and up. YAML, JSON, are both supported and you can split the file into a lot of pieces using $ref. Optic knows how to reassemble the file

- Is committing to the repo the only way for it to work --- right now, yes. But we have an API you can use too. Do you not commit your specs? Happy to help you set something else up

- If I have "Enforce Jira Keys" in Bitbucket turned on, but then generate this in my pipeline, that's not going to work without a long running Jira issue just to commit these changes against, right? -- correct, you'll need to commit it to the repo, but the "Enforce Jira Keys" option should not impact anything with the API tab.

Does that make sense? Worth hoping on a call?

[David Harper]

Hey Aidan,

Thanks for the quick response. No, we haven't been committing them. They're available on the application itself at `/swagger` (using https://elysiajs.com/plugins/swagger.html) and then as part of the pipeline I cURL a copy from the endpoint locally into a git ignored folder and pass that to Terraform.

I was hoping to just use that gitignored copy and cURL it somewhere but if there is API documentation somewhere or an example repo that'd be very handy and then I don't have to mess with making extra commits to the repo (especially as it is currently "run release on changes to `main`")

[Aidan Cunniffe]

Hey @David Harper just checked, we do have a new API endpoint to upload specs and it is stable now. 

Let me put in a request to have it documented on the API page for Compass and if it's urgent (like needs to work this week) we can set up a call to do it together 

[David Harper]

Hey @Aidan Cunniffe ,

Not urgent in the next week but maybe in the next month would be nice. :)

Happy to give the API a go and if I have more questions then have a call then?

Cheers,

Dave

[David Harper]

Hey @Aidan Cunniffe , any update on the documentation for this?

Can't find anything on https://developer.atlassian.com/cloud/compass/rest/intro/#about

[David Harper]

https://developer.atlassian.com/cloud/compass/graphql/#mutations_createComponentApiUpload

Is this the API?

Will there be a Bitbucket Pipe in the future to make this easier?

[Aidan Cunniffe]

https://community.atlassian.com/t5/Compass-articles/Announcement-Upload-OpenAPI-to-the-API-tab-using-Curl/ba-p/2934103#M648

^ Public now