Add CI check to prevent API documentation drift
- Dominant language
- JavaScript
- Stars
- 67
- Forks
- 37
- Avg merge
- 2d 12h
- Merged PRs (30d)
- 5
Description
https://github.com/GSA/touchpoints/pull/2085 added Rswag as a tool to generate API documentation. That PR originally included a new CI step that ran the Rswag script to generate `public/api/v1/openapi.yml` and failed the build if the CI-generated file did not match the versioned file in the repo. This was to check that developers are re-running the API generation script before commits so the spec does not drift from the actual API.
The step looked like this:
```
# Verify the committed OpenAPI spec is in sync with the rswag request specs.
# swaggerize regenerates public/api/v1/openapi.yml from spec/requests/api/**;
# if the result differs from what is committed, the spec has drifted and the
# build fails. Runs the full (unsplit) rswag suite on one container only so the
# generated spec is complete.
- run:
name: Verify OpenAPI spec is up to date
command: |
if [ "$CIRCLE_NODE_INDEX" != "0" ]; then
echo "Skipping OpenAPI sync check on parallel container $CIRCLE_NODE_INDEX"
exit 0
fi
set -euo pipefail
# RSWAG_DRY_RUN=0 is required so rswag runs the request examples and
# the after-callbacks that capture response bodies as OpenAPI examples.
# --dry-run is enabled by default on RSpec 3, which would skip them.
RSWAG_DRY_RUN=0 bundle exec rake rswag:specs:swaggerize
if ! git diff --exit-code -- public/api/v1/openapi.yml; then
echo "ERROR: public/api/v1/openapi.yml is out of date."
echo "Run 'RSWAG_DRY_RUN=0 bundle exec rake rswag:specs:swaggerize' locally and commit the result."
exit 1
fi
echo "OpenAPI spec is up to date."
```
This check kept failing because of minor whitespace changes between the YAML file generated on my computer vs the YAML file generated on the CI server. I removed the check to get the PR merged. This ticket is a follow-up to figure out the right way to deal with machine-specific YAML formatting, so that the CI check can be added back in.
Contributor guide
No contributing guide indexed for this repository
Research direction
Start with the Rswag generation command, public/api/v1/openapi.yml, and the request specs under spec/requests/api/**. Run RSWAG_DRY_RUN=0 bundle exec rake rswag:specs:swaggerize locally and compare its output with CI-generated output to identify machine-specific formatting. Done means a reliable comparison approach is defined and the CI drift check can be restored without false failures.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- ruby
- Domain
- api, ci-cd, documentation
- Issue type
- Feature
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 48/100