How to add a Gitlab CI job to validate generated open-api documentation is up-to-date

You can use git diff --exit-code after running the generation script to assert whether files have changed.

For example, suppose you modify an existing file then run git diff --exit-code, the command will exit non-zero. In a gitlab job, that means the job will fail.

$ echo "foo" >> existing-file.txt
$ git diff --exit-code # exits non-zero (failure)

So, you could have a gitlab job that runs your generation script then checks if the files have changed. If the files don't change, the command exits 0 and the job passes.

check_openapi:
  stage: .pre
  # ...
  script:
    - ./mvnw verify  # generate the openapi docs
    - git diff --exit-code  # fails if the files tracked by git have changed

It's important to note that git diff will only work on tracked git files. Therefore, if your generation code potentially adds new files, you should make sure that you run git add --intent-to-add for any newly created files. Otherwise, you may miss some cases because new files aren't tracked by git by default. You can add this to the CI job or you can incorporate it into your code generation script.

In example:

$ echo "foo" > newfile.txt
$ git diff --exit-code  # exits 0 (success?!)

$ echo "foo" > newfile.txt
$ git add --intent-to-add ./newfile.txt
$ git diff --exit-code # exits non-zero (failure)

So, if your generation script doesn't run git add --intent-to-add as part of its process, a complete solution may look like this:

check_openapi:
  stage: .pre
  # ...
  script:
    - ./mvnw verify
    - git add --intent-to-add .  # make sure new files are tracked/diff'd
    - git diff --exit-code