GSA / GSA/touchpoints

Add CI check to prevent API documentation drift

Open
#2,088 0 comments 0 reactions 0 assignees View on GitHub
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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.