DOP-5448: Integrate Bump GH action to generate spec pages #530
Conversation
| file: ${{matrix.spec-mapping.file}} | ||
| branch: ${{matrix.spec-mapping.branch}} | ||
|
|
||
| api-preview: |
There was a problem hiding this comment.
what is the experience to access the preview spec on bump once the job is completed? I am wondering if we should add a step here to add a comment to the PR with the link to the spec
There was a problem hiding this comment.
Right now, each matrix job will result in a separate preview link in the GH action logs (example). Would you like me to file a separate ticket to investigate the best way to comment on the PR (probably without spamming a comment for each one) or is this sufficient for now?
There was a problem hiding this comment.
Right now, each matrix job will result in a separate preview link in the GH action logs
SGTM. Feel free to introduce it in separate PR and spec out how to get access to preview urls.
| const __dirname = path.dirname(__filename); | ||
|
|
||
| // Add new specs to be deployed to Bump here | ||
| const SPEC_MAPPING = [ |
There was a problem hiding this comment.
Can we document how this array will grow over time?
I'm trying to establish how many matrix jobs this PR will render after we merge and how this will grow over time. Short explanation would do the job
There was a problem hiding this comment.
I updated the comment to be more explicit, but let me know if you need that written out elsewhere or if you need a better explanation!
Right now, it'll create a separate job for each major spec version of the Atlas Admin API, and for each resource version. Docs currently supports 1-2 more additional public OpenAPI specs, which means we may add them to this repo, leading to more jobs, but I wasn't sure if this repo is intended for all OpenAPI specs, or if the preference is to only have this repo be for Atlas Admin API exclusively.
If the number of jobs becomes a concern, what we could potentially do is explore creating a custom action that can accept the entire array as a single input and bulk deploy/preview everything instead of relying on Bump's action that only accepts 1 at a time.
There was a problem hiding this comment.
SGTM. It is not about how many jobs but how many minutes are used.
I see that in current scenario this new job will use less than 10 minutes of run time monthly which seems fine.
Co-authored-by: Andrea Angiolillo <[email protected]>
…to DOP-5448-bump
| }, | ||
| ]; | ||
|
|
||
| function handleAdminAPIv2() { |
There was a problem hiding this comment.
nit: can we please have unit tests?
There was a problem hiding this comment.
(ok to add in a follow-up PR)
There was a problem hiding this comment.
Okay, I can file a follow-up DOP ticket. Is there an ideal location within the repo to add this test? I didn't see a test directory for existing action scripts, but maybe I missed it 😅
There was a problem hiding this comment.
good point! I am not sure, in our case, we have scripts but they call some of the tools we built under the tools folder, which is where we have the most logic, if you think you'll build more on top of this script you can look into https://github.com/mongodb/openapi/tree/main/tools/spectral/ipa and create a tool folder for docs and have tests there, otherwise we can look into GH best practices on how to add coverage for the scripts!
| const versions = JSON.parse(fs.readFileSync(filePath, 'utf8')); | ||
|
|
||
| if (!versions || !Array.isArray(versions)) { | ||
| return; |
There was a problem hiding this comment.
nit: add logs for troubleshooting in the future, if file changes and we fail to parse
| const openapiFilename = `openapi-${version}.json`; | ||
| const openapiFilePath = path.join(path.dirname(filePath), openapiFilename); | ||
|
|
||
| if (!fs.existsSync(openapiFilePath)) { |
There was a problem hiding this comment.
nit: add logs if we find a version but not a file
5 participants
Proposed changes
Jira ticket: DOP-5448
The main goal of this PR is to follow Bump.sh's recommendation for a GH action that deploys changes to an OpenAPI spec to Bump, to be uploaded to the DOP team's Bump account.
Checklist
Changes to Spectral
Further comments
Some implementation details to note:
versions.jsonarray. Right now, thegenerateSpecMappingscript is mostly for the Atlas Admin API, but hopefully the array/script can be extended to handle any future OpenAPI specs that may be added to this repo.