Auto-generate swagger documentation #5470
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
|
Review app deployed to https://cpd-ecf-review-5470-web.test.teacherservices.cloud |
ethax-ross
force-pushed
the
3960-fix-swagger
branch
from
eb58fca to
772e0c6
Compare
ethax-ross
force-pushed
the
3960-fix-swagger
branch
from
772e0c6 to
61fdf72
Compare
Sort the links by a predefined order for each category of endpoints. There are minor differences with the ordering within the groups when compared to production. I opted for ordering by group and then by the length of the path, but maybe alphabetical would make more sense.
Now that the order of the sidebar links is fixed, we can auto-generate the API documentation. It was verified in #5439 that only the ordering changes when you generate the swagger docs.
We can generate the swagger docs in CI and comapre them to the version committed to the codebase to ensure there are no differences.
ethax-ross
force-pushed
the
3960-fix-swagger
branch
from
61fdf72 to
2d1054f
Compare
leandroalemao
approved these changes
Jan 24, 2025
cwrw
approved these changes
Jan 27, 2025
mooktakim
approved these changes
Jan 27, 2025
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Jira-3960
Context
Historically we haven't been able to auto-generate the v3 API documentation as it results in the links in the api-reference page becoming out of order.
We want to be able to auto-generate all the API documentation going forward so that we don't have to maintain it manually.
Changes proposed in this pull request
Sort the links by a predefined order for each category of endpoints. There are minor differences with the ordering within the groups when compared to production. I opted for ordering by group and then by the length of the path, but maybe alphabetical would make more sense?
Now that the order of the sidebar links is fixed, we can auto-generate the API documentation. It was verified in #5439 that only the ordering changes when you generate the swagger docs.
We can generate the swagger docs in CI and comapre them to the version committed to the codebase to ensure there are no differences.
Guidance to review
Example run to test failure
I've ordered by group to match prod and then by path length. In prod I think we're ordered by group and then how recently the endpoint was added (latest at the bottom). We could also try grouped then alphabetical if that would make more sense 🤔