Skip to content

Add CI check to prevent API documentation drift #2088

Description

@sanason

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

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Fields

    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions