#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.
#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.ymland 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:
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.